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

package/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md — @fcg-labs/cx-agent-hook
+
+이 패키지를 고객사 관리자 화면(CMS)에 붙이거나 올리는 작업을 맡은 에이전트는
+**`skills/cx-agent-hook-setup/SKILL.md`** 를 먼저 읽고 그 절차(실측 → 결정 규칙 →
+6단계 → 완료 체크리스트)를 따른다. 인용해도 되는 API 이름은 같은 폴더의
+`reference.md` 가 정본이며 `test/skills.test.js` 가 실제 export 와 대조한다.
+
+- 셋업 = 답변 초안 패널 **+ 처리 카드(`adminApi`)** 까지. 관리자 API 가 있는 프로젝트에서
+  `adminApi` 를 빼먹으면 미완이다.
+- 서버 코드·새 엔드포인트·서명·토큰 발급을 만들지 않는다. 비밀을 저장소에 넣지 않는다.
+- 프로젝트 성격(프레임워크·번들러·경로 별칭·요청 헬퍼 시그니처)에 맞춰 코드를 조정하되,
+  스킬에 없는 API 를 지어내지 않는다.
+
+설치: `npx cx-agent-hook skills install [--all]` (프로젝트의 `.claude/skills/`·`.cursor/rules/`·`AGENTS.md`).

package/MIGRATION.md

@@ -1,3 +1,85 @@
+# 0.4.0 → 0.5.0 마이그레이션
+
+## 요약 — 처리 액션 표면만 바뀐다 (0.3.0 표면은 그대로)
+
+0.4.0 의 처리 액션은 "허브가 고객사 서버(실행기)를 부른다"였다 — 고객사에게 어댑터
+서버·서명 검증·단명 토큰을 요구했다. 0.5.0 은 **실행기가 CMS 자신**이다: 브라우저가
+CMS 의 기존 관리자 API 를 CMS 세션으로 부르고, 허브는 원장(선점·결과·잠금)만이다.
+0.4.0 을 실배선한 소비처는 없었다(CMS 는 0.3.0). `createCxAgent`·`session`·어댑터·
+클래스명은 전부 그대로 (기존 시험 107건 무수정 통과, 액션 시험 17건 재작성).
+
+## 깨지는 것 (0.4.0 액션 표면만)
+
+- `createCxAgent({ actorAssertion })` **삭제** → `createCxAgent({ adminApi })`.
+  `adminApi = { request, endpoints, map?, onAuthExpired? }` — CMS 에 **이미 있는**
+  요청 헬퍼(예: `TempAdminApi.request`)와 엔드포인트 맵(예: `EndPoint`)의 참조.
+- `session.reconcileAction(requestId)` **삭제** → 조회 대상(고객사 서버 lookup)이 없다.
+  대신 `session.resendResult(requestId)`(미보고 결과 재보고, 재실행 아님) ·
+  `session.flushUnreportedActions()` · `session.refreshActionLocks()`.
+- `ActionResult` 에서 `actorAttested`·`auditRef`·`result` 삭제(고객사 서버 응답 개념),
+  `reported`·`targetKey` 추가. `state` 에 `received`(선점 완료) 추가.
+- 뷰: `ACTION_CLS.reconcile` → `locked`·`resend`; `ActionOfferItemView.canReconcile/
+  reconcileLabel` → `canResend/resendLabel` + `available/locked/lockedText/unavailableText`.
+  트리 action `"reconcile"` → `"resend"`. 로케일 키 `ui_action_reconcile` → `ui_action_resend`,
+  신설 `ui_action_locked`·`ui_action_unavailable`·`ui_action_unreported`.
+
+## 새로 생긴 것
+
+- `agent.candidatesReady` / `agent.publishActionCandidates({force})` — 초기화 시 엔드포인트
+  맵의 키·메서드·경로 템플릿(호스트 없음)을 허브에 1회 발행(로컬 지문 마커로 재발행 0).
+- `offer.execution`(카탈로그 실행 사양 원문)·`offer.target_key`, `session.offers` 가
+  `available`(이 CMS 가 API 를 아는가)·`locked`(같은 대상·입력 최근 성공)를 병합.
+- `actions.js` 순수 함수: `buildCandidateSnapshot`·`resolveExecution`·`judgeResponse`·
+  `executeViaAdminApi` (agent 에서 재수출).
+- 어댑터 처리 카드: `/react` `ActionOffersPanel` · `/vue` `ActionOffersPanel` · `/element`
+  `<cx-action-offers>`(`defineCxActionOffers`, 이벤트 `cx-action-result`) + `styles.css` `.fcx-act-*`.
+  0.4.0 의 "소비처가 actionOffersTree 로 직접 그린다"는 더 이상 필요 없다(헤드리스는 그대로 가능).
+
+## 에이전트 스킬 (신설)
+
+패키지에 `skills/cx-agent-hook-setup/`(SKILL.md·reference.md)과 `npx cx-agent-hook skills install`
+CLI 가 들어 있다. 개발자가 자기 코딩 에이전트에게 "cx-agent-hook 셋업 도와줘" 라고만 해도
+실측→adminApi 포함 배선→처리 카드→확인까지 하게 만드는 절차다. `AGENTS.md` 도 같은 곳을 가리킨다.
+
+## 행동 계약
+
+- 선점(①) 없이는 CMS 를 부르지 않는다 (원장 없는 실행 금지). CMS 호출(②)·보고(③)는
+  **재시도 0**. 선점만 미도달 확정(404) 시 1회 재전송.
+- `unknown`(전송 후 결과 불명·5xx)은 재실행 버튼이 없다 — 카드가 "확인 필요"로 남고,
+  공장 관측의 "확인 필요 24h+" 칩이 정본. 미보고는 `resendResult` 로만 수렴(재실행 0).
+- 잠금은 편의다: 정본은 허브 원장과 CMS 자기 API 의 정책. 다른 입력이면 허용.
+
+---
+
+# 0.3.0 → 0.4.0 마이그레이션
+
+## 요약 — 깨지는 것은 없다
+
+0.4.0 은 **추가형**이다. 0.3.0 표면(`createCxAgent`·`session`·어댑터·클래스명)은
+전부 그대로 동작한다 (기존 시험 107건 무수정 통과, 신규 10건).
+
+## 새로 생긴 것 — 처리 액션 (선택)
+
+- `createCxAgent({ actorAssertion })` — 고객사가 발행한 단명·목적 한정 행위자
+  토큰을 돌려주는 함수. **넘기지 않으면 아무것도 바뀌지 않는다** (표면 닫힘).
+- `session.offers` / `session.attachActionUi(ui)` / `session.executeAction(offer)` /
+  `session.reconcileAction(requestId)` / `session.pendingActions()`
+- `agent.actionsEnabled`
+- 헤드리스: `actionOffersView` · `actionOffersTree` · `ACTION_CLS` (`view.js`)
+- 로케일 키 `ui_action_*` 14종 (ko 정본, en/ja/zh-TW 미검수)
+- 저장: `storage.actionsImpl` — 눌렀던 처리의 pending 기록(기본 localStorage,
+  종단 후 24h). 세션 영속(sessionStorage 30분)과 **수명이 다르다**.
+
+## 행동 계약 (새 표면에만 해당)
+
+- 실행 요청은 **재시도 0**. 네트워크 오류 → 상태 조회 1회 → 허브에 기록이
+  없을 때(404)만 같은 request_id 로 1회 재전송.
+- `unknown`(실행 여부 미확인)은 재실행 버튼이 없다 — `reconcileAction`(조회)로만
+  수렴한다. 화면이 이 규칙을 어기면 이중 실행이 된다.
+- 결과 `result` 는 서버 화이트리스트 키만 온다. GET 상태 조회에는 `result` 가 없다.
+
+---
+
 # 0.2.x → 0.3.0 마이그레이션
 
 ## 요약 — 깨지는 것은 없다

package/README.md

@@ -30,6 +30,22 @@ npm install @fcg-labs/cx-agent-hook
 React·Vue 어댑터를 쓸 때만 그 프레임워크가 필요하다 (optional peer). 전송 계층만
 쓰면 의존성은 0 이다.
 
+### AI 코딩 에이전트에게 맡기기 (권장)
+
+패키지 안에 **에이전트 스킬**이 들어 있다 — 설치→환경변수→훅(`adminApi` 포함)→답변
+슬롯→처리 카드→확인까지, 프로젝트를 먼저 실측하고(프레임워크·번들러·기존 관리자 API
+헬퍼·엔드포인트 맵·세션 만료 처리·문의 화면) 그 성격에 맞춰 배선하는 절차와, 인용해도
+되는 API 이름 표(reference.md, 시험이 실제 export 와 대조)다.
+
+```bash
+npx cx-agent-hook skills install          # Claude Code: .claude/skills/cx-agent-hook-setup/
+npx cx-agent-hook skills install --all    # + Cursor 규칙(.cursor/rules) + AGENTS.md 한 줄
+npx cx-agent-hook skills path             # 그냥 "이 파일 읽고 따라줘" 라고 줄 때
+```
+그 뒤 에이전트에게 **"cx-agent-hook 셋업 도와줘"** — 답변 패널만이 아니라 처리 카드
+(adminApi)까지가 셋업이라고 스킬이 못박는다. 사람이 읽을 때는 아래 절과
+`skills/cx-agent-hook-setup/SKILL.md` 가 같은 내용이다.
+
 ## 0.3.0 — 문의별 세션 (권장 표면)
 
 `createCxHook` 은 그대로 동작한다(호환층). 문의별 초안 상태·영속이 필요한
@@ -57,6 +73,57 @@ CSS 는 사용처 `var(--fcx-*, 폴백)` 직참조라 소비처 `:root` 한 줄
 바꾼다. 다크는 조상에 `data-fcx-theme="dark"`. headless 2단계(스타일 0 /
 UI 0 — `aiSuggestTree`)도 공식 표면이다.
 
+## 0.5.0 — 처리 액션 (브라우저 실행기: 실행기는 CMS 자신)
+
+답변 제안 옆에 **처리 선택지**가 실릴 수 있다 (`payload.suggested_actions`). 이 SDK 는
+그 선택지를 보관·표시하고, 상담사 확인 뒤 **CMS 의 기존 관리자 API 를 CMS 세션으로**
+불러 처리하고, 결과를 허브 원장에 보고한다. 허브는 어떤 고객사 서버도 부르지 않는다.
+**고객사 개발자가 새로 짜는 코드는 없다** — 이미 있는 요청 헬퍼와 엔드포인트 맵의
+참조 두 개를 옵션으로 넘길 뿐이다.
+
+```js
+import TempAdminApi, { EndPoint } from "@/constant/TempAdminApi";   // CMS 에 이미 있는 것
+import TempAdminApiMap from "@/constant/TempAdminApiMap";
+const agent = createCxAgent({
+  baseUrl, token, domain,
+  adminApi: { request: TempAdminApi.request, endpoints: EndPoint, map: TempAdminApiMap,
+              onAuthExpired: handleAuthExpiredResponse },   // 없으면 액션 표면은 닫힌다
+});
+const session = agent.session(inquiryId);
+session.attachActionUi({ setOffers: (offers, pending) => render(offers, pending) });
+// 사람 확인(확인 문구·고위험은 2단) 뒤에만:
+const r = await session.executeAction(offer, { actorClaimed: agentDisplayName });
+// r.state: succeeded | failed | unknown — unknown 은 재실행 없음("확인 필요"로 남는다)
+// 보고가 안 됐으면(r.reported=false) session.resendResult(r.requestId) — 재실행 아님
+```
+
+3단: ① 허브 선점(request_id ULID, 전송 전 영속, 재시도 0 — 네트워크 오류면 상태를
+묻고 기록이 없을 때만 같은 request_id 로 1회 재전송) → ② `adminApi.request` 1회 —
+카탈로그의 실행 사양(`offer.execution`)이 `$name` 을 `params_bound` 로 치환하고
+`response_rule` 이 성공/실패를 읽는다 → ③ 결과 보고(허브가 상태 단조·멱등 보장).
+
+초기화 시 SDK 가 엔드포인트 맵의 **키·메서드·경로 템플릿(호스트 없음)** 을 허브에
+1회 발행한다 — 공장 시스템 탭의 "이 CMS 가 이미 하는 처리" 목록이 여기서 온다.
+같은 지문이면 네트워크 0(`agent.candidatesReady`, `publishActionCandidates({force})`).
+
+처리 카드 슬롯은 어댑터 한 줄이다 — React `ActionOffersPanel`(`/react`), Vue `ActionOffersPanel`
+(`/vue`), 그 밖은 `<cx-action-offers>`(`/element`, `defineCxActionOffers()`), 스타일은 같은
+`styles.css`(`.fcx-act-*`). 확인 2단·고위험 체크·재실행 금지·미보고 재보고 규약을 컴포넌트가 갖는다:
+
+```jsx
+import { ActionOffersPanel } from "@fcg-labs/cx-agent-hook/react";
+<ActionOffersPanel session={agent.session(csId)} agent={agent} actorClaimed={answerWriter}
+                   onResult={(r) => r.state === "succeeded" && refresh()} />
+```
+
+카드 상태: `locked`(같은 대상·같은 입력의 최근 성공 — "이미 처리됨 · 시각 · 행위자")
+· `unavailable`(이 CMS 가 그 API 를 모름 — fail-closed) · 실행 중 · 완료 · 실패(재시도
+가능) · 확인 필요(unknown) · 미보고(결과 다시 보고). 눌렀던 처리는
+`session.pendingActions()` 로 새로고침 뒤에도 안다(정본은 허브 원장). 헤드리스 뷰:
+`actionOffersView` / `actionOffersTree`(`view.js`), 클래스 `fcx-act-*`, 문구는
+`ui_action_*` 로케일 키. 순수 함수 `buildCandidateSnapshot` · `resolveExecution` ·
+`judgeResponse` · `executeViaAdminApi` (`actions.js`) 는 시험·커스텀 경로용으로 공개.
+
 ## 지원 프레임워크
 
 | 진입점 | 대상 | 필요한 peer |

package/actions.js

@@ -0,0 +1,168 @@
+/**
+ * 처리 액션 — 브라우저 실행기 프로파일(actions/1 프로파일 B)의 순수 함수.
+ *
+ * 실행기는 CMS 자신이다: 이 SDK 는 CMS 가 주입한 `adminApi`(요청 헬퍼 + 엔드포인트
+ * 맵)로 **CMS 의 기존 관리자 API 를 CMS 세션으로** 부르고, 결과를 허브 원장에
+ * 보고한다. 허브는 어떤 고객사 서버도 부르지 않는다. 고객사 개발자가 새로 짜는
+ * 코드는 0 — 훅 옵션 한 줄(`adminApi: { request, endpoints, map, onAuthExpired }`)뿐.
+ *
+ * 여기 있는 것 전부가 결정적·의존성 0 이라 시험이 쉽고, 어느 CMS 든 같다:
+ *   buildCandidateSnapshot  — 엔드포인트 맵 → "이 CMS 가 이미 하는 처리" 스냅샷 (호스트 제거)
+ *   resolveExecution        — 카탈로그 실행 사양의 `$name` 을 offer.params_bound 로 치환
+ *   judgeResponse           — 응답 → succeeded | failed | unknown (카탈로그 response_rule)
+ *   executeViaAdminApi      — 위 둘을 이어 CMS API 1회 호출 (재시도 0)
+ */
+
+const METHODS = ["get", "post", "put", "patch", "delete"];
+
+/** 원점(스킴+호스트) 제거 — `http://h/x/:id` → `/x/:id`, 상대 경로면 그대로. */
+export function stripOrigin(url) {
+  const s = String(url || "").trim();
+  const m = /^[a-z][a-z0-9+.-]*:\/\/[^/]*(\/.*)?$/i.exec(s);
+  if (m) return m[1] || "/";
+  return s.startsWith("/") ? s : (s ? "/" + s : "");
+}
+
+/** 결정적 64bit 지문(FNV-1a ×2) — 스냅샷 멱등 키. 암호학적 용도 아님. */
+export function fingerprint(text) {
+  const s = String(text);
+  let h1 = 0x811c9dc5, h2 = 0x01000193 ^ 0x9747b28c;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0;
+    h2 = Math.imul(h2 ^ c, 0x01000193) >>> 0;
+  }
+  return h1.toString(16).padStart(8, "0") + h2.toString(16).padStart(8, "0");
+}
+
+/**
+ * 엔드포인트 맵 → 후보 스냅샷. `endpoints` 는 {KEY: urlTemplate}, `map` 은
+ * {method: {urlTemplate: {}}}(화이트리스트; 없으면 메서드 []). 키 정렬·호스트 제거.
+ * @returns {{snapshotHash:string, items:Array<{endpoint_key:string, methods:string[], path_template:string}>}}
+ */
+export function buildCandidateSnapshot(adminApi) {
+  const endpoints = (adminApi && adminApi.endpoints && typeof adminApi.endpoints === "object") ? adminApi.endpoints : {};
+  const map = (adminApi && adminApi.map && typeof adminApi.map === "object") ? adminApi.map : {};
+  const items = [];
+  for (const key of Object.keys(endpoints).sort()) {
+    const url = endpoints[key];
+    if (typeof url !== "string" || !url) continue;
+    const methods = METHODS.filter((m) => map[m] && typeof map[m] === "object" && map[m][url] !== undefined);
+    items.push({ endpoint_key: key, methods, path_template: stripOrigin(url) });
+  }
+  return { snapshotHash: fingerprint(JSON.stringify(items)), items };
+}
+
+function subst(mapping, bound, missing) {
+  const out = {};
+  for (const [k, v] of Object.entries(mapping || {})) {
+    if (typeof v === "string" && v.startsWith("$")) {
+      const name = v.slice(1);
+      if (bound[name] === undefined || bound[name] === null || bound[name] === "") { missing.push(name); continue; }
+      out[k] = String(bound[name]);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * 실행 사양 + params_bound → 호출 인자. endpoints 에 키가 없으면 ok:false(endpoint_missing) —
+ * fail-closed 는 여기(브라우저)다: 카탈로그가 승인돼 있어도 이 CMS 가 그 API 를
+ * 모르면 카드는 열리지 않는다.
+ * @returns {{ok:boolean, error?:string, missing?:string[], method?:string, url?:string,
+ *            path?:object, query?:object, data?:object}}
+ */
+export function resolveExecution(execution, paramsBound, endpoints) {
+  const ex = execution && typeof execution === "object" ? execution : null;
+  if (!ex || !ex.endpoint_key) return { ok: false, error: "no_execution" };
+  const url = endpoints && typeof endpoints === "object" ? endpoints[ex.endpoint_key] : undefined;
+  if (typeof url !== "string" || !url) return { ok: false, error: "endpoint_missing", endpointKey: ex.endpoint_key };
+  const method = String(ex.method || "").toLowerCase();
+  if (!METHODS.includes(method)) return { ok: false, error: "invalid_method" };
+  const bound = paramsBound && typeof paramsBound === "object" ? paramsBound : {};
+  const missing = [];
+  const path = subst(ex.path, bound, missing);
+  const query = subst(ex.query, bound, missing);
+  const data = subst(ex.data, bound, missing);
+  if (missing.length) return { ok: false, error: "params_missing", missing };
+  return { ok: true, method, url, endpointKey: ex.endpoint_key, path, query, data };
+}
+
+const has = (list, code) => Array.isArray(list) && list.some((c) => String(c) === String(code));
+
+/**
+ * 응답 판정 — 계약 §B.5. 규칙은 카탈로그(response_rule)에서 온다: 성공 판정이 음성
+ * 정의(code≠4000, HTTP 항상 200)인 CMS 가 실측됐기 때문에 기본값이 없다.
+ *   HTTP 4xx → failed/http_client_error · 5xx → unknown/http_server_error(적용됐을 수 있음)
+ *   2xx: auth_expired_codes → failed/auth_expired · failure_codes 또는 success_field===false → failed/business
+ *        · 그 외 succeeded
+ *   전송 실패·타임아웃 → unknown/transport (호출자가 err 로 넘긴다)
+ * @returns {{state:"succeeded"|"failed"|"unknown", reasonCode:string, message:string, authExpired:boolean}}
+ */
+export function judgeResponse(rule, { httpStatus, body, error } = {}) {
+  const r = rule && typeof rule === "object" ? rule : {};
+  if (error) return { state: "unknown", reasonCode: "transport", message: String(error.message || error || "").slice(0, 200), authExpired: false };
+  const st = Number(httpStatus) || 0;
+  if (st >= 500) return { state: "unknown", reasonCode: "http_server_error", message: `HTTP ${st}`, authExpired: false };
+  if (st >= 400) return { state: "failed", reasonCode: "http_client_error", message: `HTTP ${st}`, authExpired: st === 401 || st === 403 };
+  if (st < 200 || st >= 300) return { state: "unknown", reasonCode: "http_other", message: `HTTP ${st}`, authExpired: false };
+  const b = body && typeof body === "object" ? body : {};
+  const codeField = String(r.code_field || "code");
+  const code = b[codeField];
+  const msg = String(b.message || b.msg || "").slice(0, 200);
+  if (code !== undefined && has(r.auth_expired_codes, code)) {
+    return { state: "failed", reasonCode: "auth_expired", message: msg, authExpired: true };
+  }
+  if (code !== undefined && has(r.failure_codes, code)) {
+    return { state: "failed", reasonCode: "business", message: msg, authExpired: false };
+  }
+  const sf = String(r.success_field || "");
+  if (sf && b[sf] === false) {
+    return { state: "failed", reasonCode: "business", message: msg, authExpired: false };
+  }
+  return { state: "succeeded", reasonCode: "", message: "", authExpired: false };
+}
+
+/** axios 응답·평문 응답 양쪽 수용 — {status, data}. */
+function normalizeResponse(res) {
+  if (res && typeof res === "object" && typeof res.status === "number" && "data" in res) {
+    return { httpStatus: res.status, body: res.data };
+  }
+  return { httpStatus: 200, body: res };
+}
+
+/**
+ * CMS API 1회 호출 + 판정. **재시도 0.** adminApi.request({method,url,path,query,data}) 는
+ * CMS 의 기존 헬퍼(예: TempAdminApi.request) 참조 — 세션 인증·화이트리스트·진행바는
+ * 그 헬퍼의 몫이다. 반환은 허브 보고 형태.
+ * @returns {Promise<{state:string, reasonCode:string, message:string, httpStatus:number,
+ *                    latencyMs:number, authExpired:boolean, body?:any}>}
+ */
+export async function executeViaAdminApi(adminApi, offer) {
+  const resolved = resolveExecution(offer && offer.execution, offer && offer.params_bound, adminApi && adminApi.endpoints);
+  if (!resolved.ok) {
+    return { state: "failed", reasonCode: resolved.error === "endpoint_missing" ? "endpoint_missing" : "invalid_execution",
+             message: resolved.error, httpStatus: 0, latencyMs: 0, authExpired: false };
+  }
+  const rule = (offer.execution && offer.execution.response_rule) || {};
+  const started = Date.now();
+  let out;
+  try {
+    const res = await adminApi.request({ method: resolved.method, url: resolved.url,
+                                         path: resolved.path, query: resolved.query, data: resolved.data });
+    const { httpStatus, body } = normalizeResponse(res);
+    out = { ...judgeResponse(rule, { httpStatus, body }), httpStatus, body };
+  } catch (err) {
+    // axios 류: err.response 가 있으면 전송·수신은 됐다 → 상태코드로 판정
+    const resp = err && err.response;
+    if (resp && typeof resp.status === "number") {
+      out = { ...judgeResponse(rule, { httpStatus: resp.status, body: resp.data }), httpStatus: resp.status, body: resp.data };
+    } else {
+      out = { ...judgeResponse(rule, { error: err || new Error("transport") }), httpStatus: 0 };
+    }
+  }
+  out.latencyMs = Date.now() - started;
+  return out;
+}

package/agent.d.ts

@@ -39,9 +39,42 @@ export type CxAgentSetup = Partial<CxAgentConfig> & {
   source?: string;
   /** 초안 후처리 사슬 — 기본 [koreanGreetingDecorator]. 비한국어 테넌트는 [] */
   draftDecorators?: DraftDecorator[];
-  storage?: SessionStorageConfig;
+  storage?: SessionStorageConfig & {
+    /** 처리 액션 pending 저장소 구현 (기본 localStorage) — 세션 영속과 수명이 다르다 */
+    actionsImpl?: Storage;
+  };
+  /**
+   * 처리 액션 (actions/1 프로파일 B — 브라우저 실행기): CMS 의 **기존** 관리자 API
+   * 헬퍼와 엔드포인트 맵을 참조로 넘긴다. 없으면 액션 표면은 닫힌다 (선택지는 오되
+   * 실행 버튼이 없다). 고객사가 새로 짜는 코드는 없다 — 이미 있는 것 두 개의 참조.
+   *   request:      ({method,url,path,query,data}) → axios 응답 {status,data} 또는 본문
+   *   endpoints:    {KEY: urlTemplate}  (`:param` 표기)
+   *   map?:         {method: {urlTemplate: {}}} 화이트리스트 — 후보 메서드 추출용
+   *   onAuthExpired?: 세션 만료 판정(response_rule.auth_expired_codes) 시 호출
+   */
+  adminApi?: AdminApi;
 };
 
+export interface AdminApi {
+  request: (args: { method: string; url: string; path?: Record<string, string>;
+                    query?: Record<string, string>; data?: Record<string, unknown> }) => Promise<unknown>;
+  endpoints: Record<string, string>;
+  map?: Record<string, Record<string, unknown>>;
+  onAuthExpired?: (body: unknown) => void;
+}
+
+/** 카탈로그 실행 사양 (offer 에 원문 그대로 실린다 — `$name` 은 params_bound 의 name) */
+export interface ActionExecution {
+  endpoint_key: string;
+  method: "get" | "post" | "put" | "patch" | "delete";
+  path: Record<string, string>;
+  query: Record<string, string>;
+  data: Record<string, unknown>;
+  target_from: string[];
+  response_rule: { success_field?: string; code_field?: string; failure_codes?: Array<number | string>;
+                   auth_expired_codes?: Array<number | string> };
+}
+
 export interface ComposeHandle {
   promise: Promise<AnswerResult>;
   abort: () => void;
@@ -85,6 +118,80 @@ export declare class InquirySession {
   scored(score: number, agent?: string): void;
   edited(finalText: string, agent?: string): void;
   discarded(agent?: string, note?: string): void;
+
+  // ── 처리 액션 (actions/1) ──
+  /** 마지막 답변의 처리 선택지 (만료 제외). 실행 시맨틱 없음 — 사람 확인 후 executeAction */
+  readonly offers: ActionOffer[];
+  /** 선택지 UI sink — setOffers(offers, pending) 를 받는다 */
+  attachActionUi(ui: { setOffers: (offers: ActionOffer[], pending: PendingAction[]) => void }): void;
+  detachActionUi(): void;
+  /** 이 문의에서 눌렀던 처리들 (정본은 허브 원장 — 브라우저 소실은 표시 손실뿐) */
+  pendingActions(): PendingAction[];
+  /**
+   * 실행 (3단) — 확인은 호출자가 끝낸 뒤. ① 허브 선점(request_id 발급·전송 전 영속·재시도 0)
+   * ② adminApi.request 로 CMS 자기 API 1회 ③ 결과 보고. unknown 은 재실행하지 않는다.
+   */
+  executeAction(offer: ActionOffer, opts?: { actorClaimed?: string }): Promise<ActionResult & { requestId: string }>;
+  /** 미보고 결과 재보고 (재실행 아님) — pending.unreported 인 것만 */
+  resendResult(requestId: string): Promise<{ ok: boolean; state?: string; error: string | null; httpStatus?: number }>;
+  /** 미보고 전부 재보고 — offer 갱신 시 자동 1회 */
+  flushUnreportedActions(): Promise<void>;
+  /** 잠금 조회 — target_key 있는 offer 마다 허브에 1회(세션 캐시). offers 의 locked 에 반영 */
+  refreshActionLocks(): Promise<void>;
+}
+
+/** 답변 payload 의 suggested_actions 항목 (허브 평탄화 뷰 — endpoint·트리거·승인 시각 없음) */
+export interface ActionOffer {
+  offer_id: string;
+  event_id: string;
+  action_key: string;
+  params_bound: Record<string, string>;
+  params_hash: string;
+  params_display: string;
+  label: string;
+  description: string;
+  confirm: string;
+  risk_level: "low" | "medium" | "high";
+  expires_at: string;
+  catalog_version: number;
+  offer_reason: "issue_key" | "context" | "tokens";
+  /** 프로파일 B: 실행 사양 (원문) 과 잠금 축 */
+  execution: ActionExecution | Record<string, never>;
+  target_key: string;
+  /** session.offers 가 병합하는 브라우저 판정 — 이 CMS 가 API 를 아는가 / 같은 대상·입력 최근 성공 */
+  available?: boolean;
+  locked?: boolean;
+  lock?: { at: string; actorClaimed: string; requestId: string } | null;
+}
+
+export interface PendingAction {
+  requestId: string;
+  offerId: string;
+  actionKey: string;
+  targetKey?: string;
+  paramsHash?: string;
+  label: string;
+  state: "pending" | "received" | "succeeded" | "failed" | "unknown" | string;
+  reasonCode?: string;
+  message?: string;
+  /** 실행은 끝났으나 허브 보고가 안 됨 — resendResult 대상 */
+  unreported?: boolean;
+  at: number;
+}
+
+export interface ActionResult {
+  ok: boolean;
+  /** received | succeeded | failed | unknown | '' */
+  state: string;
+  reasonCode: string;
+  message: string;
+  targetKey?: string;
+  deduplicated?: boolean;
+  /** 보고까지 끝났는가 (false 면 unreported — resendResult) */
+  reported?: boolean;
+  /** offer_locked | request_conflict | endpoint_missing | admin_api_missing | network_error | … */
+  error: string | null;
+  httpStatus?: number;
 }
 
 export interface CxAgent {
@@ -110,6 +217,12 @@ export interface CxAgent {
   investigationStatus(
     externalId: string | number,
   ): Promise<{ ok: boolean; status: string; jobId?: number; error: string | null }>;
+  /** 처리 액션 표면 열림 여부 — 전송 3요소 + adminApi(request·endpoints) */
+  readonly actionsEnabled: boolean;
+  /** 후보 발행 완료 신호 (초기화 시 1회 자동) */
+  candidatesReady: Promise<{ ok: boolean; unchanged?: boolean; count?: number; snapshotHash?: string; error?: string | null }>;
+  /** 후보 재발행 — force 로 로컬 마커 무시 */
+  publishActionCandidates(opts?: { force?: boolean }): Promise<{ ok: boolean; unchanged?: boolean; count?: number; snapshotHash?: string; error?: string | null }>;
   inquirySent(payload: {
     externalId: string | number;
     inquiry: string;
@@ -124,3 +237,17 @@ export declare function createCxAgent(config?: CxAgentSetup): CxAgent;
 export declare const koreanGreetingDecorator: DraftDecorator;
 export declare function notConfiguredResult(): AnswerResult;
 export declare function textOf(messages: Record<string, string>, reason: string): string;
+
+// 헤드리스 액션 뷰 재수출 (view.d.ts 정본)
+export { ACTION_CLS, actionOffersTree, actionOffersView } from "./view.js";
+export type { ActionOfferItemView } from "./view.js";
+// 브라우저 실행기 순수 함수 (actions.js) — 시험·커스텀 실행 경로용
+export declare function buildCandidateSnapshot(adminApi: Pick<AdminApi, "endpoints" | "map">):
+  { snapshotHash: string; items: Array<{ endpoint_key: string; methods: string[]; path_template: string }> };
+export declare function resolveExecution(execution: unknown, paramsBound: Record<string, string>, endpoints: Record<string, string>):
+  { ok: boolean; error?: string; missing?: string[]; method?: string; url?: string;
+    path?: Record<string, string>; query?: Record<string, string>; data?: Record<string, unknown> };
+export declare function judgeResponse(rule: unknown, input: { httpStatus?: number; body?: unknown; error?: unknown }):
+  { state: "succeeded" | "failed" | "unknown"; reasonCode: string; message: string; authExpired: boolean };
+export declare function executeViaAdminApi(adminApi: AdminApi, offer: ActionOffer):
+  Promise<{ state: "succeeded" | "failed" | "unknown"; reasonCode: string; message: string; httpStatus: number; latencyMs: number; authExpired: boolean; body?: unknown }>;

package/agent.js

@@ -1,5 +1,6 @@
 /**
- * CxAgent — 0.3.0 객체 표면. `createCxAgent(config)` 하나로 테넌트를 세운다.
+ * CxAgent — 0.3.0 객체 표면 (0.5.0: 처리 액션 브라우저 실행기). `createCxAgent(config)`
+ * 하나로 테넌트를 세운다.
  *
  * 구조 원칙 (객체화의 이유):
  *   - **보편 구조는 코어가 소유한다** — 어느 CMS 든 존재하는 것들: 설정
@@ -23,9 +24,16 @@
  * session.answerSent(finalText, agentId);   // gold 쌍 후킹 + 세션 소멸
  * ```
  */
-import { CxAgentClient } from "./client.js";
+import { CxAgentClient, newRequestId } from "./client.js";
 import { LOCALES, MESSAGES, normalizeLocale, resolveMessages } from "./locales.js";
-import { InquirySession, SessionStore } from "./session.js";
+import { ActionLedger, InquirySession, SessionStore } from "./session.js";
+import { ACTION_CLS, actionOffersTree, actionOffersView } from "./view.js";
+import { buildCandidateSnapshot, executeViaAdminApi, judgeResponse, resolveExecution } from "./actions.js";
+
+// 헤드리스 액션 뷰 — 프레임워크 어댑터(react/vue) 슬롯은 0.4.x 후속. 그전엔
+// 소비처가 이 순수 함수로 자기 렌더러에 그린다 (텍스트 노드만 — innerHTML 금지).
+export { ACTION_CLS, actionOffersTree, actionOffersView };
+export { buildCandidateSnapshot, executeViaAdminApi, judgeResponse, resolveExecution };
 
 export { LOCALES, MESSAGES, normalizeLocale };
 
@@ -86,6 +94,11 @@ export function createCxAgent(config = {}) {
     source = "cms",
     draftDecorators = [koreanGreetingDecorator],
     storage = {},
+    // 처리 액션 (actions/1 프로파일 B — 브라우저 실행기): CMS 의 기존 관리자 API
+    // 헬퍼와 엔드포인트 맵을 참조로 넘긴다 — { request, endpoints, map?, onAuthExpired? }.
+    // 없으면 액션 표면은 닫힌다 (offers 는 오되 실행 버튼은 없다). 고객사가 새로
+    // 짜는 코드는 없다: 이미 있는 것 두 개의 참조뿐 (0.4.x actorAssertion 폐기).
+    adminApi,
     ...rest
   } = config;
 
@@ -174,12 +187,45 @@ export function createCxAgent(config = {}) {
         },
       });
 
+  const actionLedger = storage.enabled === false || !client
+    ? null
+    : new ActionLedger({ impl: storage.actionsImpl, prefix: `cx-agent-actions:${domain}` });
+  const admin = adminApi && typeof adminApi === "object" && typeof adminApi.request === "function"
+    && adminApi.endpoints && typeof adminApi.endpoints === "object" ? adminApi : null;
   const sessionDeps = {
     client, messages, decorate, store,
     textOf: (reason) => textOf(messages, reason),
+    adminApi: admin, actionLedger, newRequestId,
   };
   const sessions = new Map();
 
+  // 후보 발행 — "이 CMS 가 이미 하는 처리" 스냅샷(키·메서드·경로 템플릿, 호스트 없음).
+  // 지문이 마지막 발행과 같으면 네트워크 0 (localStorage 마커, 실패 시 다음 로드에
+  // 재시도). 허브도 같은 해시면 쓰기 0. 백그라운드 — 화면을 막지 않는다.
+  const publishCandidates = async ({ force = false } = {}) => {
+    if (!client || !admin || api !== "hub") return { ok: false, error: "not_configured" };
+    const snap = buildCandidateSnapshot(admin);
+    const key = `cx-agent-catalog:${domain}`;
+    let ls = null;
+    try { ls = storage.actionsImpl || (typeof localStorage !== "undefined" ? localStorage : null); } catch { ls = null; }
+    if (!force && ls) {
+      try {
+        const prev = JSON.parse(ls.getItem(key) || "null");
+        if (prev && prev.hash === snap.snapshotHash && Date.now() - (prev.at || 0) < 24 * 60 * 60 * 1000) {
+          return { ok: true, unchanged: true, count: snap.items.length, snapshotHash: snap.snapshotHash };
+        }
+      } catch { /* 마커 손상 — 발행 진행 */ }
+    }
+    const r = await client.publishActionCandidates(snap);
+    if (r.ok && ls) {
+      try { ls.setItem(key, JSON.stringify({ hash: snap.snapshotHash, at: Date.now() })); } catch { /* quota */ }
+    }
+    return { ...r, snapshotHash: snap.snapshotHash, count: snap.items.length };
+  };
+  const candidatesReady = admin && client && api === "hub"
+    ? publishCandidates().catch(() => ({ ok: false, error: "network_error" }))
+    : Promise.resolve({ ok: false, error: "not_configured" });
+
   return {
     /** 전송 3요소가 다 있으면 true */
     enabled: Boolean(client),
@@ -233,6 +279,13 @@ export function createCxAgent(config = {}) {
       return client.investigationStatus(externalId);
     },
 
+    /** 처리 액션 표면이 열려 있는가 — 전송 3요소 + adminApi(request·endpoints) */
+    get actionsEnabled() { return Boolean(client && sessionDeps.adminApi); },
+    /** 후보 발행 완료 신호 (초기화 시 1회 자동) — 결과 {ok, unchanged, count, snapshotHash} */
+    candidatesReady,
+    /** 후보 재발행 — force 로 마커 무시 (CMS 배포 직후 등) */
+    publishActionCandidates(opts) { return publishCandidates(opts || {}); },
+
     /** 문의+최종답변 쌍 적재 (fire-and-forget, external_id 멱등) */
     inquirySent({ externalId, inquiry, reply, agent, meta } = {}) {
       if (!client || !externalId || !inquiry) return;

package/angular.d.ts

@@ -1,5 +1,5 @@
 /** Angular 진입점 — 표준 커스텀 엘리먼트를 쓴다 (CUSTOM_ELEMENTS_SCHEMA). */
-export { defineCxAiSuggest, TAG } from "./element.js";
+export { defineCxAiSuggest, TAG, defineCxActionOffers, ACTIONS_TAG } from "./element.js";
 export { aiSuggestView } from "./view.js";
 export type { AiSuggestView } from "./view.js";
-export type { CxAiSuggestElement } from "./element.js";
+export type { CxAiSuggestElement, CxActionOffersElement } from "./element.js";

package/angular.js

@@ -34,5 +34,5 @@
  * `angular.json` 의 styles 배열)에 넣는다. 컴포넌트 스코프 스타일에 넣으면
  * 뷰 캡슐화 때문에 안 닿는다 — 이 엘리먼트는 섀도 DOM 을 쓰지 않는다.
  */
-export { defineCxAiSuggest, TAG } from "./element.js";
+export { defineCxAiSuggest, TAG, defineCxActionOffers, ACTIONS_TAG } from "./element.js";
 export { aiSuggestView } from "./view.js";

package/astro.d.ts

@@ -1,9 +1,9 @@
 import type { CxHook } from "./index.js";
 
-export { defineCxAiSuggest, TAG } from "./element.js";
+export { defineCxAiSuggest, TAG, defineCxActionOffers, ACTIONS_TAG } from "./element.js";
 export { aiSuggestView } from "./view.js";
 export type { AiSuggestView } from "./view.js";
-export type { CxAiSuggestElement } from "./element.js";
+export type { CxAiSuggestElement, CxActionOffersElement } from "./element.js";
 
 /** 엘리먼트 등록 + 값 주입 + 채택 구독을 한 번에. 반환값은 구독 해제. */
 export declare function setupCxAiSuggest(

package/astro.js

@@ -34,6 +34,7 @@
 import { defineCxAiSuggest, TAG } from "./element.js";
 
 export { defineCxAiSuggest, TAG };
+export { defineCxActionOffers, ACTIONS_TAG } from "./element.js";
 export { aiSuggestView } from "./view.js";
 
 /** 엘리먼트 등록 + 값 주입 + 채택 구독을 한 번에.