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

package/styles.css

@@ -99,6 +99,70 @@
 }
 [data-fcx-theme="dark"] .fcx-ai-declined { color: var(--fcx-warn, #d9a94e); }
 
+/* ── 처리 선택지 카드 (actions/1 프로파일 B) — 답변 패널과 같은 토큰 계약 ────────
+ * 상태는 클래스+data-state 로만 말한다: 잠김(.fcx-act-locked)·비활성(data-state=unavailable)·
+ * 실행 중/완료/실패/확인 필요(.fcx-act-status[data-state])·미보고(.fcx-act-resend). */
+.fcx-act { display: grid; gap: var(--fcx-gap, 8px); font-size: var(--fcx-font-size, 13px); color: var(--fcx-text, #1f2d3d); }
+.fcx-act-item {
+  display: grid; gap: 6px;
+  padding: var(--fcx-pad, 10px 12px);
+  border: 1px solid var(--fcx-border, #d7e3f4);
+  border-radius: var(--fcx-radius, 10px);
+  background: var(--fcx-surface, #f5f9ff);
+}
+.fcx-act-label { font-weight: 600; }
+.fcx-act-params { color: var(--fcx-muted, #5b6b7d); }
+.fcx-act-risk {
+  justify-self: start; padding: 1px 8px; border-radius: 999px;
+  font-size: calc(var(--fcx-font-size, 13px) - 1px);
+  background: var(--fcx-surface-2, #e8eef7); color: var(--fcx-muted, #5b6b7d);
+}
+.fcx-act-risk[data-risk="high"] { background: var(--fcx-warn-bg, #fbf1de); color: var(--fcx-warn, #9a6a12); }
+.fcx-act-button, .fcx-act-resend {
+  justify-self: start;
+  padding: var(--fcx-button-pad, 6px 12px);
+  border: 1px solid var(--fcx-accent, #2f6fed);
+  border-radius: var(--fcx-button-radius, 8px);
+  background: var(--fcx-accent, #2f6fed); color: var(--fcx-on-accent, #fff);
+  font: inherit; cursor: pointer;
+  transition: background-color 120ms ease-out, opacity 120ms ease-out;
+}
+.fcx-act-button:hover:not(:disabled) { background: var(--fcx-accent-hover, #245ad0); }
+.fcx-act-button:disabled { opacity: var(--fcx-disabled-opacity, 0.6); cursor: not-allowed; }
+.fcx-act-resend { background: transparent; color: var(--fcx-accent, #2f6fed); }
+.fcx-act-button:focus-visible, .fcx-act-resend:focus-visible, .fcx-act-ack:focus-visible {
+  outline: 2px solid var(--fcx-accent, #2f6fed); outline-offset: 2px;
+}
+.fcx-act-confirm {
+  display: grid; gap: 6px; padding: 8px 10px;
+  border-left: 3px solid var(--fcx-accent, #2f6fed);
+  background: var(--fcx-surface-2, #e8eef7); border-radius: var(--fcx-radius, 10px);
+}
+.fcx-act-confirm-text { font-weight: 600; }
+.fcx-act-ack {
+  justify-self: start; cursor: pointer; font: inherit;
+  padding: 2px 4px; border: 0; background: transparent; border-radius: 4px;
+  color: var(--fcx-warn, #6b4a0b);   /* 확인 패널 배경(#e8eef7) 위 대비 ≥ 5:1 */
+}
+.fcx-act-ack::before { content: "☐ "; }
+.fcx-act-ack[aria-pressed="true"]::before { content: "☑ "; }
+.fcx-act-status { color: var(--fcx-muted, #5b6b7d); }
+.fcx-act-status[data-state="succeeded"] { color: var(--fcx-success, #1f7a3f); }
+.fcx-act-status[data-state="failed"] { color: var(--fcx-danger, #b42318); }
+.fcx-act-status[data-state="unknown"] { color: var(--fcx-warn, #9a6a12); }
+.fcx-act-status[data-state="unavailable"] { color: var(--fcx-muted, #5b6b7d); font-style: italic; }
+.fcx-act-locked {
+  color: var(--fcx-success, #1f7a3f);
+  padding: 4px 8px; border-radius: 6px;
+  background: var(--fcx-success-bg, #e6f4ea);
+}
+
+[data-fcx-theme="dark"] .fcx-act-item { background: var(--fcx-surface, #10182a); border-color: var(--fcx-border, #24344d); }
+[data-fcx-theme="dark"] .fcx-act { color: var(--fcx-text, #dbe6f3); }
+[data-fcx-theme="dark"] .fcx-act-params, [data-fcx-theme="dark"] .fcx-act-status { color: var(--fcx-muted, #8ba0b8); }
+[data-fcx-theme="dark"] .fcx-act-risk, [data-fcx-theme="dark"] .fcx-act-confirm { background: var(--fcx-surface-2, #182238); }
+[data-fcx-theme="dark"] .fcx-act-locked { background: var(--fcx-success-bg, #12301c); }
+
 @media (prefers-reduced-motion: reduce) {
-  .fcx-ai-button, .fcx-ai-adopt { transition: none; }
+  .fcx-ai-button, .fcx-ai-adopt, .fcx-act-button, .fcx-act-resend { transition: none; }
 }

package/view.d.ts

@@ -32,13 +32,40 @@ export interface AiSuggestNode {
   cls: string;
   text?: string;
   children?: AiSuggestNode[];
-  /** 추상 동작명 — 어댑터가 자기 이벤트 체계로 배선: "request" | "adopt" */
-  action?: "request" | "adopt";
+  /** 추상 동작명 — 어댑터가 자기 이벤트 체계로 배선. 답변 패널: "request" | "adopt" ·
+   * 처리 카드: "confirm" | "execute" | "cancel" | "ack" | "resend" */
+  action?: "request" | "adopt" | "confirm" | "execute" | "cancel" | "ack" | "resend";
   type?: string;
   disabled?: boolean;
+  /** 처리 카드 노드 부가 필드 (actionOffersTree) */
+  offerId?: string; requestId?: string; risk?: string; state?: string;
+  /** 상태 문구 = role="status" (live) · ack 토글 버튼 = aria-pressed (pressed) */
+  live?: boolean; pressed?: boolean;
 }
 
 /** 패널 전체 구조 스펙 — headless(UI 0) 소비처의 진입점이기도 하다 */
 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" | "locked" | "resend",
+  string
+>;
+export interface ActionOfferItemView {
+  offerId: string; label: string; params: string; riskLabel: string; risk: string;
+  /** 이 CMS 가 API 를 아는가 / 같은 대상·입력 최근 성공(카드 잠금) */
+  available: boolean; locked: boolean; lockedText: string; unavailableText: string;
+  canExecute: boolean; buttonLabel: string; confirming: boolean; confirmText: string;
+  needsAck: boolean; ackLabel: string; okLabel: string; cancelLabel: string;
+  state: string; statusText: string; terminal: boolean;
+  /** 미보고 결과 재보고 (재실행 아님) */
+  canResend: boolean; resendLabel: 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" | "resend" | "ack" — 텍스트 노드만 */
+export declare function actionOffersTree(input: Parameters<typeof actionOffersView>[0]): AiSuggestNode | null;

package/view.js

@@ -103,3 +103,132 @@ export function aiSuggestTree(input) {
   }
   return { tag: "div", cls: CLS.root, children };
 }
+
+
+// ── 처리 액션 (actions/1 프로파일 B) — 선택지·확인·상태·잠금의 표시 판단 ─────
+//
+// 실행 시맨틱은 여기 없다. offers 는 session.offers(available·locked 병합), pending 은
+// 세션 ActionLedger 그대로 — 이 함수는 "무엇을 어떤 상태로 보일지"만 결정한다.
+// 텍스트 노드만 (innerHTML 금지 — 고객사 기입 문구가 실린다).
+//
+// 카드 상태 (하나만):
+//   locked      같은 대상·같은 입력의 최근 성공 기록 — "이미 처리됨 · 시각 · 행위자", 버튼 없음
+//   unavailable 이 CMS 가 그 API 를 모름(endpoint_key 부재) — 회색·사유, 버튼 없음
+//   pending/received  실행 중 · succeeded · failed(재시도 가능) · unknown(확인 필요, 재실행 없음)
+//   unreported  실행은 끝났으나 허브 보고가 안 됨 — "결과 다시 보고" (재실행 아님)
+
+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",
+  locked: "fcx-act-locked",
+  resend: "fcx-act-resend",
+};
+
+const RISK_KEY = { low: "ui_action_risk_low", medium: "ui_action_risk_medium", high: "ui_action_risk_high" };
+
+function fmtWhen(iso) {
+  if (!iso) return "";
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return String(iso);
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+}
+
+/**
+ * @param {Array} offers  session.offers  (available·locked·lock 병합됨)
+ * @param {Array} pending session.pendingActions()  [{requestId, offerId, state, reasonCode, message, label, unreported}]
+ * @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";
+    const available = o.available !== false;
+    const locked = Boolean(o.locked) && !p;
+    let statusText = "";
+    if (state === "pending" || state === "received") 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;
+    if (p && p.unreported) statusText = `${statusText} · ${messages.ui_action_unreported}`;
+    let lockedText = "";
+    if (locked) {
+      const who = o.lock && o.lock.actorClaimed ? ` · ${o.lock.actorClaimed}` : "";
+      lockedText = `${messages.ui_action_locked} · ${fmtWhen(o.lock && o.lock.at)}${who}`;
+    }
+    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",
+      available, locked, lockedText,
+      unavailableText: available ? "" : messages.ui_action_unavailable,
+      // 실행 버튼: 표면 열림 ∧ 이 CMS 가 API 를 앎 ∧ 잠기지 않음 ∧ 미실행(또는 실패-재시도 가능)
+      canExecute: enabled && available && !locked && (!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 은 확인 필요로 남는다)
+      canResend: Boolean(p && p.unreported),
+      resendLabel: messages.ui_action_resend,
+      requestId: p ? p.requestId : "",
+    };
+  });
+  return { visible: items.length > 0, items, disabledHint: enabled ? "" : messages.ui_action_disabled };
+}
+
+/** 프레임워크 중립 트리 — action: "confirm"(패널 열기) / "execute" / "cancel" / "resend" / "ack".
+ * 노드 필드: tag·cls·text·children·type·action·offerId·requestId·risk·state·live(상태 = role=status)·
+ * pressed(ack 토글 — 어댑터가 aria-pressed 를 offer 단위 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.locked) {
+      children.push({ tag: "div", cls: ACTION_CLS.locked, text: it.lockedText });
+    } else if (!it.available) {
+      children.push({ tag: "div", cls: ACTION_CLS.status, text: it.unavailableText, state: "unavailable" });
+    } else if (it.confirming) {
+      children.push({
+        tag: "div", cls: ACTION_CLS.confirm, children: [
+          { tag: "div", cls: ACTION_CLS.confirmText, text: it.confirmText },
+          // 고위험 2단 확인 — 토글 **버튼**(aria-pressed): 포커스·Space/Enter 가 되어야 키보드 사용자도 실행할 수 있다
+          ...(it.needsAck ? [{ tag: "button", type: "button", cls: ACTION_CLS.ack, text: it.ackLabel, action: "ack", offerId: it.offerId, pressed: true }] : []),
+          { 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, live: true });
+    if (it.canResend) {
+      children.push({ tag: "button", cls: ACTION_CLS.resend, type: "button", text: it.resendLabel, action: "resend", 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 };
+}

package/vue.d.ts

@@ -15,4 +15,14 @@ export interface AiSuggestPanelProps {
 
 /** `@adopt` 로 채택 문구를 emit 한다. hook 이 미설정이면 아무것도 그리지 않는다. */
 export declare const AiSuggestPanel: DefineComponent<AiSuggestPanelProps>;
+
+export interface ActionOffersPanelProps {
+  session: import("./agent.js").InquirySession;
+  agent: import("./agent.js").CxAgent;
+  actorClaimed?: string;
+  className?: string;
+}
+/** 처리 선택지 카드 (actions/1 프로파일 B) — emits "result" */
+export declare const ActionOffersPanel: DefineComponent<ActionOffersPanelProps>;
+
 export default AiSuggestPanel;

package/vue.js

@@ -19,9 +19,9 @@
  * JSX·SFC 를 쓰지 않는 이유는 react.js 와 같다: 이 패키지에는 빌드 단계가 없다.
  * Vue 는 optional peer 다 (>=3.0).
  */
-import { computed, defineComponent, h, ref, watch } from "vue";
+import { computed, defineComponent, h, onBeforeUnmount, ref, watch } from "vue";
 
-import { aiSuggestTree, aiSuggestView, CLS } from "./view.js";
+import { actionOffersTree, aiSuggestTree, aiSuggestView, CLS } from "./view.js";
 
 export { aiSuggestView };
 
@@ -107,4 +107,82 @@ export const AiSuggestPanel = defineComponent({
   },
 });
 
+// ── 처리 선택지 카드 (actions/1 프로파일 B) — react.js ActionOffersPanel 과 같은 규약 ──
+//
+// ```vue
+// <ActionOffersPanel :session="getCsSession(csId)" :agent="agent" :actor-claimed="answerWriter" @result="onResult" />
+// ```
+export const ActionOffersPanel = defineComponent({
+  name: "ActionOffersPanel",
+  props: {
+    session: { type: Object, required: true },
+    agent: { type: Object, required: true },
+    actorClaimed: { type: String, default: "" },
+    className: { type: String, default: "" },
+  },
+  emits: ["result"],
+  setup(props, { emit }) {
+    const offers = ref(props.session ? props.session.offers : []);
+    const pending = ref(props.session ? props.session.pendingActions() : []);
+    const confirming = ref(null);
+    const ackedOffer = ref(null);   // 고위험 확인은 offer 단위
+    let attached = null;
+    const attach = (s) => {
+      if (attached && typeof attached.detachActionUi === "function") attached.detachActionUi();
+      attached = s || null;
+      confirming.value = null; ackedOffer.value = null;
+      if (s && typeof s.attachActionUi === "function") {
+        s.attachActionUi({ setOffers: (o, p) => { offers.value = o; pending.value = p; } });
+      }
+    };
+    watch(() => props.session, attach, { immediate: true });
+    onBeforeUnmount(() => attach(null));
+
+    const execute = async (offerId) => {
+      const offer = offers.value.find((o) => o.offer_id === offerId);
+      if (!offer) return;
+      if (offer.risk_level === "high" && ackedOffer.value !== offerId) return;
+      confirming.value = null; ackedOffer.value = null;
+      const r = await props.session.executeAction(offer, { actorClaimed: props.actorClaimed });
+      emit("result", r);
+    };
+    const actions = {
+      confirm: (e) => { confirming.value = e.currentTarget.dataset.offer || null; ackedOffer.value = null; },
+      cancel: () => { confirming.value = null; ackedOffer.value = null; },
+      ack: (e) => { const id = e.currentTarget.dataset.offer; ackedOffer.value = ackedOffer.value === id ? null : id; },
+      execute: (e) => execute(e.currentTarget.dataset.offer),
+      resend: (e) => props.session.resendResult(e.currentTarget.dataset.request),
+    };
+    const tree = computed(() => actionOffersTree({
+      offers: offers.value, pending: pending.value, enabled: Boolean(props.agent && props.agent.actionsEnabled),
+      confirming: confirming.value, messages: props.agent ? props.agent.messages : {},
+    }));
+    const render = (node) => {
+      const p = { class: node.cls };
+      if (node.tag === "button") p.type = node.type || "button";
+      if (node.action && actions[node.action]) {
+        p.onClick = actions[node.action];
+        if (node.offerId) p["data-offer"] = node.offerId;
+        if (node.requestId) p["data-request"] = node.requestId;
+        if (node.action === "execute" && confirming.value) {
+          const o = offers.value.find((x) => x.offer_id === node.offerId);
+          if (o && o.risk_level === "high" && ackedOffer.value !== node.offerId) p.disabled = true;
+        }
+        if (node.pressed) p["aria-pressed"] = ackedOffer.value === node.offerId;
+      }
+      if (node.live) p.role = "status";
+      if (node.state) p["data-state"] = node.state;
+      if (node.risk) p["data-risk"] = node.risk;
+      return h(node.tag, p, node.children ? node.children.map(render) : node.text);
+    };
+    return () => {
+      if (!props.session || !props.agent) return null;
+      const t = tree.value;
+      if (!t) return null;
+      return h("div", { class: props.className ? `${t.cls} ${props.className}` : t.cls,
+                        onClick: (event) => event.stopPropagation() }, t.children.map(render));
+    };
+  },
+});
+
 export default AiSuggestPanel;