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

package/MIGRATION.md

@@ -1,3 +1,32 @@
+# 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

@@ -57,6 +57,34 @@ CSS 는 사용처 `var(--fcx-*, 폴백)` 직참조라 소비처 `:root` 한 줄
 바꾼다. 다크는 조상에 `data-fcx-theme="dark"`. headless 2단계(스타일 0 /
 UI 0 — `aiSuggestTree`)도 공식 표면이다.
 
+## 0.4.0 — 처리 액션 (말에서 행으로, 선택 표면)
+
+답변 제안 옆에 **처리 선택지**가 실릴 수 있다 (`payload.suggested_actions`). 이 SDK 는
+그 선택지를 보관·표시하고, 상담사 확인 뒤 허브에 실행을 요청하고, 결과 3상태를
+보여준다. **실행기·권한·정책은 고객사 서버가 소유**한다 — SDK 는 계약(`actions/1`)의
+클라이언트일 뿐이다.
+
+```js
+const agent = createCxAgent({
+  baseUrl, token, domain,
+  // 고객사가 발행하는 단명·목적 한정 행위자 토큰. 없으면 액션 표면은 닫힌다
+  // (선택지는 오되 실행 버튼이 없다). 전권 세션 토큰을 넘기지 말 것.
+  actorAssertion: () => fetchMyActionToken(),
+});
+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 은 "다시 확인"(reconcile) 만, 재실행 없음
+await session.reconcileAction(r.requestId);
+```
+
+계약 요점: 요청은 request_id(ULID)로 멱등이고 SDK 는 **재시도하지 않는다** —
+네트워크 오류면 상태를 묻고, 허브에 기록이 없을 때만 같은 request_id 로 1회
+재전송한다. 눌렀던 처리는 `session.pendingActions()` 로 새로고침 뒤에도 안다
+(정본은 허브 원장). 헤드리스 뷰: `actionOffersView` / `actionOffersTree`(`view.js`),
+클래스 `fcx-act-*`, 문구는 `ui_action_*` 로케일 키.
+
 ## 지원 프레임워크
 
 | 진입점 | 대상 | 필요한 peer |

package/agent.d.ts

@@ -39,7 +39,16 @@ export type CxAgentSetup = Partial<CxAgentConfig> & {
   source?: string;
   /** 초안 후처리 사슬 — 기본 [koreanGreetingDecorator]. 비한국어 테넌트는 [] */
   draftDecorators?: DraftDecorator[];
-  storage?: SessionStorageConfig;
+  storage?: SessionStorageConfig & {
+    /** 처리 액션 pending 저장소 구현 (기본 localStorage) — 세션 영속과 수명이 다르다 */
+    actionsImpl?: Storage;
+  };
+  /**
+   * 처리 액션 (actions/1) 행위자 자격증명 — 고객사가 발행한 **단명·목적 한정**
+   * 토큰(aud=cx-action, 분 단위 ttl)을 돌려주는 함수. 없으면 액션 표면은 닫힌다
+   * (선택지는 오되 실행 버튼이 없다). 전권 세션 토큰을 넘기는 것은 계약 위반.
+   */
+  actorAssertion?: () => string | Promise<string>;
 };
 
 export interface ComposeHandle {
@@ -85,6 +94,62 @@ 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[];
+  /** 실행 — 확인은 호출자가 끝낸 뒤. request_id 발급·전송 전 영속·재시도 0 */
+  executeAction(offer: ActionOffer, opts?: { actorClaimed?: string }): Promise<ActionResult & { requestId: string }>;
+  /** 재조정 — lookup 만 (재실행 없음). unknown 만 의미 있다 */
+  reconcileAction(requestId: string): Promise<{ ok: boolean; state: string; reasonCode?: string; message?: string; error: string | null }>;
+}
+
+/** 답변 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";
+}
+
+export interface PendingAction {
+  requestId: string;
+  offerId: string;
+  actionKey: string;
+  label: string;
+  state: "pending" | "succeeded" | "failed" | "unknown" | string;
+  reasonCode?: string;
+  message?: string;
+  at: number;
+}
+
+export interface ActionResult {
+  ok: boolean;
+  /** succeeded | failed | unknown | in_flight | '' */
+  state: string;
+  reasonCode: string;
+  message: string;
+  actorAttested: string;
+  auditRef: string;
+  result: Record<string, unknown> | null;
+  deduplicated: boolean;
+  /** offer_locked | request_conflict | actor_assertion_required | actions_disabled | network_error | … */
+  error: string | null;
+  httpStatus: number;
 }
 
 export interface CxAgent {
@@ -110,6 +175,8 @@ export interface CxAgent {
   investigationStatus(
     externalId: string | number,
   ): Promise<{ ok: boolean; status: string; jobId?: number; error: string | null }>;
+  /** 처리 액션 표면 열림 여부 — 전송 3요소 + actorAssertion */
+  readonly actionsEnabled: boolean;
   inquirySent(payload: {
     externalId: string | number;
     inquiry: string;
@@ -124,3 +191,7 @@ 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";

package/agent.js

@@ -23,9 +23,14 @@
  * 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";
+
+// 헤드리스 액션 뷰 — 프레임워크 어댑터(react/vue) 슬롯은 0.4.x 후속. 그전엔
+// 소비처가 이 순수 함수로 자기 렌더러에 그린다 (텍스트 노드만 — innerHTML 금지).
+export { ACTION_CLS, actionOffersTree, actionOffersView };
 
 export { LOCALES, MESSAGES, normalizeLocale };
 
@@ -86,6 +91,9 @@ export function createCxAgent(config = {}) {
     source = "cms",
     draftDecorators = [koreanGreetingDecorator],
     storage = {},
+    // 처리 액션 (actions/1): 고객사가 발행한 단명·목적 한정 행위자 토큰을 돌려주는
+    // 함수. 없으면 액션 표면은 닫힌다 (offers 는 오되 실행 버튼은 없다).
+    actorAssertion,
     ...rest
   } = config;
 
@@ -174,9 +182,14 @@ export function createCxAgent(config = {}) {
         },
       });
 
+  const actionLedger = storage.enabled === false || !client
+    ? null
+    : new ActionLedger({ impl: storage.actionsImpl, prefix: `cx-agent-actions:${domain}` });
   const sessionDeps = {
     client, messages, decorate, store,
     textOf: (reason) => textOf(messages, reason),
+    actorAssertion: typeof actorAssertion === "function" ? actorAssertion : null,
+    actionLedger, newRequestId,
   };
   const sessions = new Map();
 
@@ -233,6 +246,9 @@ export function createCxAgent(config = {}) {
       return client.investigationStatus(externalId);
     },
 
+    /** 처리 액션 표면이 열려 있는가 — 전송 3요소 + actorAssertion 함수 */
+    get actionsEnabled() { return Boolean(client && sessionDeps.actorAssertion); },
+
     /** 문의+최종답변 쌍 적재 (fire-and-forget, external_id 멱등) */
     inquirySent({ externalId, inquiry, reply, agent, meta } = {}) {
       if (!client || !externalId || !inquiry) return;

package/client.js

@@ -37,6 +37,8 @@ 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: (d) => `/v1/domains/${d}/actions`,
   },
   // platform 은 인그레스 API 미제공 (공장 큐레이션 파이프라인이 담당)
 };
@@ -591,6 +593,123 @@ export class CxAgentClient {
       clearTimeout(timer);
     }
   }
+
+  // ── 처리 액션 (actions/1) ──────────────────────────────────────────────
+  //
+  // **재시도 0.** sendFeedback 의 5xx 재시도 루프를 여기 쓰면 비멱등 실행이 두 번
+  // 간다. 네트워크 오류면 호출자가 actionStatus(request_id) 로 원장을 묻고,
+  // 404(미도달 확정)일 때만 같은 request_id 로 1회 재전송한다 (client 밖 규칙).
+
+  /**
+   * 실행 요청. 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}>}
+   */
+  async requestAction({ requestId, offer, actorAssertion, 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 };
+    }
+    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 || ""),
+      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 || "",
+        actorAttested: d.actor_attested || "", auditRef: d.audit_ref || "",
+        result: d.result ?? null, 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 잠김 — 그대로 전달
+      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 };
+    }
+  }
+
+  /** 상태 조회 — 원장 뷰(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}` };
+      },
+    );
+  }
+
+  /** 재조정 — lookup 전용 (재실행 아님). unknown 만 의미 있고 종단이면 그대로 온다. */
+  async actionReconcile(requestId) {
+    if (this.api !== "hub" || !requestId) return { ok: false, state: "", error: "unsupported" };
+    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 };
+      }
+      return { ok: false, state: "", error: data.error || `http_${status}` };
+    } catch (err) {
+      this.onError(err, { op: "actionReconcile", code: "network_error" });
+      return { ok: false, state: "", error: "network_error" };
+    }
+  }
+
+  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/locales.js

@@ -31,6 +31,20 @@ 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_reconcile: "Check again",
+  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 +71,20 @@ 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_reconcile: "다시 확인",
+  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 +106,20 @@ 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_reconcile: "再確認",
+  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 +141,20 @@ 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_reconcile: "再次確認",
+  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/package.json

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

package/session.js

@@ -20,6 +20,48 @@
  * 남기지 않는다 — 프라이버시 경계).
  */
 
+/** 처리 액션 pending 저장소 — 세션 영속(_persist·TTL 30분·consume 삭제)과
+ * **수명이 다르다**: 요청은 전송 **전에** 남고, 종단 뒤 24h 까지 살아 새로고침·
+ * 재진입 시 "이미 눌렀던 것" 을 안다. 정본은 허브 원장이다 — 브라우저 소실은
+ * 기록 손실이 아니라 표시 손실일 뿐. localStorage 부재면 메모리로만 산다. */
+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 +151,8 @@ export class InquirySession {
     this._statusText = "";
     this._answerId = null;
     this._composeSeq = 0;
+    this._offers = [];              // 마지막 답변의 처리 선택지 (actions/1 §4)
+    this._actionUi = null;
 
     // 영속 복원 — TTL 만료분은 store 가 이미 걸렀다
     if (this._id && deps.store) {
@@ -123,6 +167,64 @@ export class InquirySession {
   }
 
   get externalId() { return this._id; }
+  /** 처리 선택지 (만료 제외). 실행 여부는 pendingActions() 로. */
+  get offers() {
+    const now = Date.now();
+    return this._offers.filter((o) => !o.expires_at || Date.parse(o.expires_at) > now);
+  }
+  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) : [];
+  }
+  /**
+   * 처리 실행 — 사람 확인은 호출자(UI)가 끝낸 뒤 부른다. request_id 를 발급해
+   * **전송 전에** 영속하고, 재시도 0. 네트워크 오류면 상태 조회 1회 → 404(미도달)
+   * 일 때만 같은 request_id 로 1회 재전송 (실행된 적 없음이 확정이라 안전).
+   */
+  async executeAction(offer, { actorClaimed } = {}) {
+    const d = this._d;
+    if (!d.client || !offer || !offer.offer_id) return { ok: false, state: "", error: "not_configured" };
+    if (typeof d.actorAssertion !== "function") return { ok: false, state: "", error: "actor_assertion_missing" };
+    let assertion = "";
+    try { assertion = String(await d.actorAssertion() || ""); } catch { assertion = ""; }
+    if (!assertion) return { ok: false, state: "", error: "actor_assertion_missing" };
+    const requestId = d.newRequestId();
+    const rec = { externalId: this._id, offerId: offer.offer_id, actionKey: offer.action_key,
+                  label: offer.label || "", state: "pending" };
+    if (d.actionLedger) d.actionLedger.put(requestId, rec);
+    const args = { requestId, offer, actorAssertion: assertion, 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, reasonCode: st.reasonCode, message: st.message, error: null };
+      else r = { ...r, state: "unknown", error: "network_error" };
+    }
+    if (d.actionLedger) d.actionLedger.put(requestId, { ...rec, state: r.state || (r.ok ? "unknown" : "failed"),
+                                                        reasonCode: r.reasonCode || "", message: r.message || "" });
+    this._notifyActions();
+    return { requestId, ...r };
+  }
+  /** 재조정 — lookup 만. 재실행 버튼은 존재하지 않는다. */
+  async reconcileAction(requestId) {
+    const d = this._d;
+    if (!d.client || !requestId) return { ok: false, state: "", error: "not_configured" };
+    const r = await d.client.actionReconcile(requestId);
+    if (d.actionLedger && r.ok) {
+      const prev = d.actionLedger.get(requestId) || { externalId: this._id };
+      d.actionLedger.put(requestId, { ...prev, state: r.state, reasonCode: r.reasonCode || "", message: r.message || "" });
+    }
+    this._notifyActions();
+    return r;
+  }
   get state() { return this._state; }
   get draft() { return this._draft; }
   get adoptedAnswerId() { return this._answerId; }
@@ -263,6 +365,10 @@ 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 (result.answered) {
         this._draft = decorate(result.answer); // 정본 확정 (strip+데코레이터)
         this._setUiDraft(this._draft);

package/view.d.ts

@@ -42,3 +42,22 @@ export interface AiSuggestNode {
 export declare function aiSuggestTree(
   input: Parameters<typeof aiSuggestView>[0],
 ): AiSuggestNode;
+
+// ── 처리 액션 (actions/1) 뷰 ──
+export declare const ACTION_CLS: Record<
+  "root" | "item" | "label" | "params" | "risk" | "button" | "confirm" | "confirmText" | "ack" | "status" | "reconcile",
+  string
+>;
+export interface ActionOfferItemView {
+  offerId: string; label: string; params: string; riskLabel: string; risk: string;
+  canExecute: boolean; buttonLabel: string; confirming: boolean; confirmText: string;
+  needsAck: boolean; ackLabel: string; okLabel: string; cancelLabel: string;
+  state: string; statusText: string; terminal: boolean;
+  canReconcile: boolean; reconcileLabel: string; requestId: string;
+}
+export declare function actionOffersView(input: {
+  offers?: unknown[]; pending?: unknown[]; enabled?: boolean; confirming?: string | null;
+  messages?: Record<string, string>;
+}): { visible: boolean; items: ActionOfferItemView[]; disabledHint: string };
+/** action: "confirm" | "execute" | "cancel" | "reconcile" | "ack" — 텍스트 노드만 */
+export declare function actionOffersTree(input: Parameters<typeof actionOffersView>[0]): AiSuggestNode | null;

package/view.js

@@ -103,3 +103,100 @@ export function aiSuggestTree(input) {
   }
   return { tag: "div", cls: CLS.root, children };
 }
+
+
+// ── 처리 액션 (actions/1) — 선택지·확인·3상태의 표시 판단 ─────────────────
+//
+// 실행 시맨틱은 여기 없다. offers 는 답변 payload 의 suggested_actions 그대로,
+// pending 은 세션 ActionLedger 그대로 — 이 함수는 "무엇을 어떤 상태로 보일지"
+// 만 결정한다. 텍스트 노드만 (innerHTML 금지 — 고객사 기입 문구가 실린다).
+
+export const ACTION_CLS = {
+  root: "fcx-act",
+  item: "fcx-act-item",
+  label: "fcx-act-label",
+  params: "fcx-act-params",
+  risk: "fcx-act-risk",
+  button: "fcx-act-button",
+  confirm: "fcx-act-confirm",
+  confirmText: "fcx-act-confirm-text",
+  ack: "fcx-act-ack",
+  status: "fcx-act-status",
+  reconcile: "fcx-act-reconcile",
+};
+
+const RISK_KEY = { low: "ui_action_risk_low", medium: "ui_action_risk_medium", high: "ui_action_risk_high" };
+
+/**
+ * @param {Array} offers  session.offers
+ * @param {Array} pending session.pendingActions()  [{requestId, offerId, state, reasonCode, message, label}]
+ * @param {boolean} enabled  agent.actionsEnabled
+ * @param {string|null} confirming  확인 패널이 열린 offer_id
+ * @param {Record<string,string>} messages
+ */
+export function actionOffersView({ offers = [], pending = [], enabled = true, confirming = null, messages = {} }) {
+  const byOffer = new Map();
+  for (const p of pending) byOffer.set(p.offerId, p);
+  const items = offers.map((o) => {
+    const p = byOffer.get(o.offer_id) || null;
+    const state = p ? p.state : "";
+    const terminal = state === "succeeded" || state === "failed";
+    let statusText = "";
+    if (state === "pending") statusText = messages.ui_action_running;
+    else if (state === "succeeded") statusText = messages.ui_action_succeeded;
+    else if (state === "failed") statusText = `${messages.ui_action_failed}${p && p.message ? " — " + p.message : ""}`;
+    else if (state === "unknown") statusText = messages.ui_action_unknown;
+    return {
+      offerId: o.offer_id, label: o.label || o.action_key, params: o.params_display || "",
+      riskLabel: messages[RISK_KEY[o.risk_level] || RISK_KEY.low] || "",
+      risk: o.risk_level || "low",
+      // 실행 버튼: 표면 열림 ∧ 미실행(또는 실패-재시도 가능) — unknown 은 재실행 없음
+      canExecute: enabled && (!p || (state === "failed")),
+      buttonLabel: messages.ui_action_execute,
+      confirming: confirming === o.offer_id,
+      confirmText: o.confirm || messages.ui_action_confirm_default,
+      needsAck: o.risk_level === "high",
+      ackLabel: messages.ui_action_ack,
+      okLabel: messages.ui_action_confirm_ok,
+      cancelLabel: messages.ui_action_confirm_cancel,
+      state, statusText, terminal,
+      // unknown 만 "다시 확인" (reconcile=lookup) — 재실행 버튼은 없다
+      canReconcile: state === "unknown",
+      reconcileLabel: messages.ui_action_reconcile,
+      requestId: p ? p.requestId : "",
+    };
+  });
+  return { visible: items.length > 0, items, disabledHint: enabled ? "" : messages.ui_action_disabled };
+}
+
+/** 프레임워크 중립 트리 — action: "confirm"(패널 열기) / "execute" / "cancel" / "reconcile" / "ack" */
+export function actionOffersTree(input) {
+  const v = actionOffersView(input);
+  if (!v.visible) return null;
+  const items = v.items.map((it) => {
+    const children = [
+      { tag: "div", cls: ACTION_CLS.label, text: it.label },
+      ...(it.params ? [{ tag: "div", cls: ACTION_CLS.params, text: it.params }] : []),
+      { tag: "span", cls: ACTION_CLS.risk, text: it.riskLabel, risk: it.risk },
+    ];
+    if (it.confirming) {
+      children.push({
+        tag: "div", cls: ACTION_CLS.confirm, children: [
+          { tag: "div", cls: ACTION_CLS.confirmText, text: it.confirmText },
+          ...(it.needsAck ? [{ tag: "label", cls: ACTION_CLS.ack, text: it.ackLabel, action: "ack", offerId: it.offerId }] : []),
+          { tag: "button", cls: ACTION_CLS.button, type: "button", text: it.okLabel, action: "execute", offerId: it.offerId },
+          { tag: "button", cls: ACTION_CLS.button, type: "button", text: it.cancelLabel, action: "cancel", offerId: it.offerId },
+        ],
+      });
+    } else if (it.canExecute) {
+      children.push({ tag: "button", cls: ACTION_CLS.button, type: "button", text: it.buttonLabel, action: "confirm", offerId: it.offerId });
+    }
+    if (it.statusText) children.push({ tag: "div", cls: ACTION_CLS.status, text: it.statusText, state: it.state });
+    if (it.canReconcile) {
+      children.push({ tag: "button", cls: ACTION_CLS.reconcile, type: "button", text: it.reconcileLabel, action: "reconcile", requestId: it.requestId });
+    }
+    return { tag: "div", cls: ACTION_CLS.item, children };
+  });
+  if (v.disabledHint) items.push({ tag: "div", cls: ACTION_CLS.status, text: v.disabledHint });
+  return { tag: "div", cls: ACTION_CLS.root, children: items };
+}