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

package/session.js

@@ -0,0 +1,455 @@
+/**
+ * InquirySession — 문의 1건의 AI 초안 수명주기 (0.3.0 객체화의 핵).
+ *
+ * **초안의 정본은 세션 버퍼다.** compose 스트림은 UI 가 아니라 버퍼에
+ * 쓰고, UI 는 붙였다 뗐다 하는 sink 다 (`attachUi`/`detachUi`). 이 분리가
+ * 0.2.x 의 두 실결함을 구조의 귀결로 없앤다:
+ *   ① 메뉴 이탈 → 복귀 시 초안 소실 (초안이 컴포넌트 로컬 상태였다)
+ *      — 이제 이탈은 detachUi 일 뿐, 스트림은 버퍼로 완주하고 복귀는
+ *        restore() 한 줄이다.
+ *   ② 스트림 중 문의 전환 시 이전 문의 텍스트가 새 에디터를 오염
+ *      — sink 를 뗀 스트림은 화면에 닿을 길 자체가 없다.
+ *
+ * 상태기계: idle → composing → drafted | declined.
+ * consume 규칙은 0.2.x 승계 — sent·discarded 가 그 제안의 마지막 판단
+ * (기록을 비운다), scored·edited 는 발송 전 여러 번 가능.
+ *
+ * 영속(sessionStorage): externalId 가 있는 세션만. TTL·LRU 캡을 넘긴
+ * 퇴거는 `discarded(note:"session_expired")` 로 원장에 남긴다 — 침묵
+ * 소거 금지 원칙의 연장. consume 시 즉시 삭제 (발송된 초안을 브라우저에
+ * 남기지 않는다 — 프라이버시 경계).
+ */
+
+/** 처리 액션 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: {},
+});
+
+/** 세션 영속 저장소 — TTL·LRU 캡·퇴거 통지. sessionStorage 부재(SSR·Node)면
+ * 전부 무동작 (세션은 메모리로만 산다). */
+export class SessionStore {
+  constructor({ impl, prefix, ttlMs, maxSessions, onEvict } = {}) {
+    this.impl = impl !== undefined
+      ? impl
+      : (typeof sessionStorage !== "undefined" ? sessionStorage : null);
+    this.prefix = prefix || "cx-agent-session";
+    this.ttlMs = ttlMs ?? 30 * 60 * 1000;
+    this.maxSessions = maxSessions ?? 20;
+    this.onEvict = onEvict || (() => {});
+  }
+
+  _key(id) { return `${this.prefix}:${id}`; }
+
+  load(id) {
+    if (!this.impl) return null;
+    try {
+      const rec = JSON.parse(this.impl.getItem(this._key(id)) || "null");
+      if (!rec) return null;
+      if (Date.now() - rec.at > this.ttlMs) {
+        this.remove(id);
+        this.onEvict(rec, "session_expired");
+        return null;
+      }
+      return rec;
+    } catch { return null; }
+  }
+
+  save(id, rec) {
+    if (!this.impl) return;
+    try {
+      this.impl.setItem(this._key(id), JSON.stringify({ ...rec, at: Date.now() }));
+      this._touchIndex(id);
+    } catch { /* 용량 초과 등 — 영속 실패가 세션을 막지 않는다 */ }
+  }
+
+  remove(id) {
+    if (!this.impl) return;
+    try {
+      this.impl.removeItem(this._key(id));
+      const idx = this._index().filter((x) => x !== id);
+      this.impl.setItem(`${this.prefix}:index`, JSON.stringify(idx));
+    } catch { /* 무시 */ }
+  }
+
+  _index() {
+    try {
+      return JSON.parse(this.impl.getItem(`${this.prefix}:index`) || "[]");
+    } catch { return []; }
+  }
+
+  _touchIndex(id) {
+    // LRU: 최근 사용을 꼬리로 — 캡 초과 시 머리(가장 오래됨)부터 퇴거
+    const idx = this._index().filter((x) => x !== id);
+    idx.push(id);
+    while (idx.length > this.maxSessions) {
+      const evictId = idx.shift();
+      try {
+        const rec = JSON.parse(this.impl.getItem(this._key(evictId)) || "null");
+        this.impl.removeItem(this._key(evictId));
+        if (rec) this.onEvict(rec, "session_evicted");
+      } catch { /* 무시 */ }
+    }
+    try {
+      this.impl.setItem(`${this.prefix}:index`, JSON.stringify(idx));
+    } catch { /* 무시 */ }
+  }
+}
+
+export class InquirySession {
+  /**
+   * 직접 만들지 않는다 — `agent.session(externalId)` 가 만든다.
+   * @param {object} deps  agent 가 닫아 넣는 내부 의존 (전송·문구·데코레이터)
+   */
+  constructor(externalId, deps) {
+    this._id = externalId == null ? "" : String(externalId);
+    this._d = deps;                // {client, messages, decorate, store, onError}
+    this._ui = null;
+    this._state = "idle";
+    this._draft = "";
+    this._statusText = "";
+    this._answerId = null;
+    this._composeSeq = 0;
+    this._offers = [];              // 마지막 답변의 처리 선택지 (actions/1 §4)
+    this._actionUi = null;
+
+    // 영속 복원 — TTL 만료분은 store 가 이미 걸렀다
+    if (this._id && deps.store) {
+      const rec = deps.store.load(this._id);
+      if (rec) {
+        this._draft = rec.draft || "";
+        this._answerId = rec.answerId ?? null;
+        this._state = rec.state === "declined" ? "declined"
+          : (this._draft || this._answerId ? "drafted" : "idle");
+      }
+    }
+  }
+
+  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; }
+
+  /** UI sink 연결 — 초안을 자동 주입하지 않는다 (복원은 restore() 명시 호출).
+   * @param {{getDraft?:()=>string, setDraft:(t:string)=>void,
+   *          setStatus?:(t:string)=>void}} ui */
+  attachUi(ui) {
+    this._ui = ui && typeof ui.setDraft === "function" ? ui : null;
+    return this;
+  }
+
+  /** UI 분리 — 진행 중 스트림은 버퍼로 계속 완주한다 (중단이 아니다). */
+  detachUi() {
+    this._ui = null;
+    return this;
+  }
+
+  /** 세션 정본을 UI 로 — 복귀 시 한 줄. UI 없으면 값만 돌려준다. */
+  restore() {
+    if (this._ui) {
+      this._ui.setDraft(this._draft);
+      if (this._ui.setStatus) this._ui.setStatus(this._statusText);
+    }
+    return { draft: this._draft, answerId: this._answerId, state: this._state };
+  }
+
+  /** 상담사 편집을 정본에 반영 (에디터 onChange → 스로틀은 소비처 몫). */
+  remember(text) {
+    this._draft = String(text ?? "");
+    if (this._state === "idle" && this._draft) this._state = "drafted";
+    this._persist();
+  }
+
+  _persist() {
+    if (this._id && this._d.store) {
+      this._d.store.save(this._id, {
+        draft: this._draft, answerId: this._answerId, state: this._state,
+      });
+    }
+  }
+
+  _clearPersist() {
+    if (this._id && this._d.store) this._d.store.remove(this._id);
+  }
+
+  _setUiDraft(text) { if (this._ui) this._ui.setDraft(text); }
+
+  _setStatus(text) {
+    this._statusText = text || "";
+    if (this._ui && this._ui.setStatus) this._ui.setStatus(this._statusText);
+  }
+
+  /**
+   * AI 초안 생성 — 스트림은 세션 버퍼에 쌓이고 UI 는 sink 로만 받는다.
+   * 의미론은 0.2.x composeDraft 와 동일 (자동 채택·교체 기각·실패 원복·
+   * abort 무간섭) + UI 분리에서도 성립.
+   *
+   * idleTimeoutMs/overallTimeoutMs: 스트림 시한 관통 — 큰 컨텍스트 창
+   * 운영(프리필 분 단위)은 서버 사다리와 함께 이 값도 올린다. 미지정이면
+   * 전송 계층 기본(90s/190s).
+   *
+   * @returns {{promise: Promise<object>, abort: ()=>void}}
+   */
+  compose({ inquiry, context, customerName, confirmOverwrite,
+            idleTimeoutMs, overallTimeoutMs } = {}) {
+    const d = this._d;
+    const noop = { promise: Promise.resolve(NOT_CONFIGURED()), abort: () => {} };
+    if (!d.client || !inquiry) {
+      this._setStatus(d.textOf("not_configured"));
+      return noop;
+    }
+    // "기존 초안" 의 정본: UI 가 붙어 있으면 에디터의 지금 값 (상담사가
+    // 마지막으로 본 것), 아니면 세션 버퍼.
+    const existing = this._ui && typeof this._ui.getDraft === "function"
+      ? String(this._ui.getDraft() || "")
+      : this._draft;
+    if (existing.trim() && !(confirmOverwrite && confirmOverwrite())) {
+      // 상담사가 쓰던 초안이 우선한다 — 조용히 덮지 않는다.
+      return { promise: Promise.resolve({ ...NOT_CONFIGURED(), declinedReason: "" }),
+               abort: () => {} };
+    }
+    // 새 스트림 = 이전 채택의 교체 시도 — 확정 전까지 보류 (0.2.3 계약)
+    const supersededId = this._answerId;
+    const supersededDraft = existing;
+    this._answerId = null;
+    const seq = ++this._composeSeq;
+    const stale = () => seq !== this._composeSeq;
+
+    const name = String(customerName || "").trim();
+    const contextWithName = name
+      ? { ...(context || {}), customerName: name }
+      : context;
+    const decorate = (text) => d.decorate(text, { customerName: name });
+
+    const controller = new AbortController();
+    let aborted = false;
+    let accumulated = "";
+    let pending = null;
+    const flushDraft = () => {
+      pending = null;
+      this._draft = decorate(accumulated);
+      this._setUiDraft(this._draft);
+    };
+    const queueDraft = () => {
+      // trailing 스로틀 — 청크마다 리렌더하면 큰 화면이 버벅인다
+      if (pending === null) pending = setTimeout(flushDraft, 80);
+    };
+    const clearPending = () => {
+      if (pending !== null) { clearTimeout(pending); pending = null; }
+    };
+
+    this._state = "composing";
+    this._setStatus(d.messages.ui_requesting);
+    this._draft = "";
+    this._setUiDraft("");
+
+    const promise = d.client.getAnswerStream(inquiry, contextWithName, {
+      signal: controller.signal,
+      ...(idleTimeoutMs ? { idleTimeoutMs } : {}),
+      ...(overallTimeoutMs ? { overallTimeoutMs } : {}),
+      onDelta: (text) => { accumulated += text; queueDraft(); },
+      onRestart: () => {
+        // 계약 위반 교정 — 지금까지 보인 초안은 폐기본이다
+        clearPending();
+        accumulated = "";
+        this._draft = "";
+        this._setUiDraft("");
+        this._setStatus(d.messages.ui_correcting);
+      },
+      onStage: (phase) => {
+        if (phase === "generating") this._setStatus(d.messages.ui_requesting);
+      },
+    }).then((result) => {
+      clearPending();
+      if (aborted || stale()) {
+        // 소비자 주도 중단(또는 뒤이은 compose 가 추월) — 화면·정본을 만지지
+        // 않는다. 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);
+        const newId = result.answerId ?? null;
+        if (supersededId && supersededId !== newId) {
+          // 교체 확정 — 이전 제안은 기각으로 원장에 남긴다 (침묵 소거 금지)
+          d.client.discarded(supersededId, "", "redraft");
+        }
+        this._answerId = newId;
+        this._state = "drafted";
+        this._setStatus("");
+        this._persist();
+      } else {
+        // 실패·거절 — 미완성 텍스트를 정본·화면에 남기지 않는다.
+        // 채택 기록도 함께 원복 (0.2.3 비대칭 수정 승계).
+        this._draft = supersededDraft;
+        this._answerId = supersededId;
+        this._state = supersededDraft || supersededId ? "drafted" : "declined";
+        this._setUiDraft(supersededDraft);
+        this._setStatus(d.textOf(result.declinedReason || "unknown"));
+        this._persist();
+      }
+      return result;
+    });
+    return {
+      promise,
+      abort: () => {
+        // 중단 = 화면·정본은 그대로, 원장 상태는 요청 전으로 복귀
+        aborted = true;
+        this._answerId = supersededId;
+        this._draft = supersededDraft;
+        this._state = supersededDraft || supersededId ? "drafted" : "idle";
+        clearPending();
+        controller.abort();
+      },
+    };
+  }
+
+  /** 제안을 에디터에 넣었다 (패널 채택 버튼) */
+  noteAdopted(answerId) {
+    this._answerId = answerId || null;
+    if (this._answerId) this._state = "drafted";
+    this._persist();
+  }
+
+  /** 채택 기록 폐기 — 원장 통지 없는 로컬 클리어 (0.2.x clearAdopted) */
+  clearAdopted() {
+    this._answerId = null;
+    this._persist();
+  }
+
+  _emit(send, consume) {
+    const id = this._answerId;
+    if (consume) {
+      this._answerId = null;
+      this._draft = "";
+      this._statusText = "";
+      this._state = "idle";
+      this._clearPersist();     // 발송·폐기된 초안을 브라우저에 남기지 않는다
+    }
+    if (!this._d.client || !id) return;
+    send(id);
+  }
+
+  /** 발송 — 채택본이었다면 gold 쌍 후킹, 마지막 판단이라 기록을 비운다 */
+  answerSent(finalText, agent) {
+    this._emit((id) => this._d.client.sent(id, finalText, agent), true);
+  }
+
+  /** 품질 점수 1~5 — 발송 전 여러 번 가능 (비소모) */
+  scored(score, agent) {
+    this._emit((id) => this._d.client.scored(id, score, agent), false);
+  }
+
+  /** 수정 — 초안↔최종본 델타 (비소모) */
+  edited(finalText, agent) {
+    this._emit((id) => this._d.client.edited(id, finalText, agent), false);
+  }
+
+  /** 폐기 + 이유 — 마지막 판단이라 기록을 비운다 */
+  discarded(agent, note) {
+    this._emit((id) => this._d.client.discarded(id, agent, note), true);
+  }
+}

package/styles.css

@@ -1,40 +1,104 @@
-/* AI 답변 제안 패널 기본 스타일.
+/* AI 답변 제안 패널 기본 스타일 (0.3.0 — 고객 제어권 전면 개방).
  *
  * 클래스는 `fcx-` 로 시작한다 — 소비처(고객사 관리자 화면)의 이름 공간과
- * 겹치지 않게 하기 위해서다. 배치(margin·위치)는 여기서 정하지 않고 소비처가
- * `className` 으로 준다. 색·간격을 바꾸려면 아래 변수만 덮어쓰면 된다.
+ * 겹치지 않게. 배치(margin·위치)는 소비처가 `className` 으로 준다.
+ *
+ * 테마 계약: 모든 값은 `var(--fcx-*, 폴백)` **사용처 직참조**다 — 컴포넌트가
+ * 토큰을 자체 선언하지 않으므로 소비처는 `:root { --fcx-accent: … }` 한 줄로
+ * 전체 팔레트를 바꾼다 (0.2.x 는 `.fcx-ai` 가 토큰을 선언해 :root 를 가렸다).
+ * 다크는 조상 어디든 `[data-fcx-theme="dark"]` 를 달면 켜진다.
+ *
+ * headless 2단계:
+ *   ① 스타일 0 — 이 파일을 import 하지 않으면 마크업만 남는다 (클래스 유지)
+ *   ② UI 0 — 어댑터 대신 `aiSuggestTree`/세션 표면만 쓰면 DOM 도 소비처 소유
  */
 .fcx-ai {
-  --fcx-accent: #2f6fed;
-  --fcx-surface: #f5f9ff;
-  --fcx-border: #d7e3f4;
-  --fcx-text: #1f2d3d;
-  --fcx-muted: #5b6b7e;
-  --fcx-warn: #8a5a00;
-
-  padding: 10px 12px;
-  border: 1px solid var(--fcx-border);
-  border-radius: 10px;
-  background: var(--fcx-surface);
+  padding: var(--fcx-pad, 10px 12px);
+  border: 1px solid var(--fcx-border, #d7e3f4);
+  border-radius: var(--fcx-radius, 10px);
+  background: var(--fcx-surface, #f5f9ff);
+  font-size: var(--fcx-font-size, 13px);
+  color: var(--fcx-text, #1f2d3d);
 }
 
-.fcx-ai-head { display: flex; gap: 8px; align-items: center; }
+.fcx-ai-head { display: flex; gap: var(--fcx-gap, 8px); align-items: center; }
 
 .fcx-ai-button,
 .fcx-ai-adopt {
-  padding: 6px 12px;
-  border: 1px solid var(--fcx-accent);
-  border-radius: 8px;
-  font-size: 12px;
-  font-weight: 600;
+  padding: var(--fcx-button-pad, 6px 12px);
+  border: 1px solid var(--fcx-accent, #2f6fed);
+  border-radius: var(--fcx-button-radius, 8px);
+  font-size: var(--fcx-button-font-size, 12px);
+  font-weight: var(--fcx-button-weight, 600);
   cursor: pointer;
+  transition: background-color var(--fcx-motion, 150ms ease),
+              color var(--fcx-motion, 150ms ease),
+              box-shadow var(--fcx-motion, 150ms ease);
+}
+
+.fcx-ai-button {
+  background: var(--fcx-accent, #2f6fed);
+  color: var(--fcx-on-accent, #fff);
+}
+.fcx-ai-button:hover:not(:disabled) {
+  background: var(--fcx-accent-hover, #245cd0);
+}
+.fcx-ai-button:disabled {
+  opacity: var(--fcx-disabled-opacity, 0.6);
+  cursor: default;
+}
+.fcx-ai-adopt {
+  background: var(--fcx-adopt-surface, #fff);
+  color: var(--fcx-accent, #2f6fed);
+}
+.fcx-ai-adopt:hover {
+  background: var(--fcx-adopt-hover, #eef4ff);
+}
+.fcx-ai-button:focus-visible,
+.fcx-ai-adopt:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 var(--fcx-focus-ring-width, 2px)
+              var(--fcx-focus-ring, rgba(47, 111, 237, 0.45));
+}
+
+.fcx-ai-body { margin-top: var(--fcx-gap, 8px); }
+.fcx-ai-answer {
+  white-space: pre-wrap;
+  font-size: var(--fcx-font-size, 13px);
+  color: var(--fcx-text, #1f2d3d);
+}
+.fcx-ai-evidence {
+  margin-top: 6px;
+  font-size: var(--fcx-evidence-font-size, 11px);
+  color: var(--fcx-muted, #5b6b7e);
+}
+.fcx-ai-declined {
+  margin-top: var(--fcx-gap, 8px);
+  font-size: var(--fcx-button-font-size, 12px);
+  color: var(--fcx-warn, #8a5a00);
 }
 
-.fcx-ai-button { background: var(--fcx-accent); color: #fff; }
-.fcx-ai-button:disabled { opacity: 0.6; cursor: default; }
-.fcx-ai-adopt { background: #fff; color: var(--fcx-accent); }
+/* 상태 모디파이어 — 소비처·어댑터가 붙일 수 있는 선택 훅 (마크업 불변) */
+.fcx-ai--loading .fcx-ai-button { opacity: var(--fcx-disabled-opacity, 0.6); }
+.fcx-ai--declined { border-color: var(--fcx-warn-border, #e8d5b0); }
 
-.fcx-ai-body { margin-top: 8px; }
-.fcx-ai-answer { white-space: pre-wrap; font-size: 13px; color: var(--fcx-text); }
-.fcx-ai-evidence { margin-top: 6px; font-size: 11px; color: var(--fcx-muted); }
-.fcx-ai-declined { margin-top: 8px; font-size: 12px; color: var(--fcx-warn); }
+/* 다크 — 조상 [data-fcx-theme="dark"] 로 켠다. 토큰만 바꾸므로 소비처
+ * :root 오버라이드와 규칙이 같다 (더 구체적인 선언이 이긴다). */
+[data-fcx-theme="dark"] .fcx-ai {
+  border-color: var(--fcx-border, #2b3a4f);
+  background: var(--fcx-surface, #16202e);
+  color: var(--fcx-text, #dbe6f3);
+}
+[data-fcx-theme="dark"] .fcx-ai-answer { color: var(--fcx-text, #dbe6f3); }
+[data-fcx-theme="dark"] .fcx-ai-evidence { color: var(--fcx-muted, #8ba0b8); }
+[data-fcx-theme="dark"] .fcx-ai-adopt {
+  background: var(--fcx-adopt-surface, #16202e);
+}
+[data-fcx-theme="dark"] .fcx-ai-adopt:hover {
+  background: var(--fcx-adopt-hover, #1e2c3f);
+}
+[data-fcx-theme="dark"] .fcx-ai-declined { color: var(--fcx-warn, #d9a94e); }
+
+@media (prefers-reduced-motion: reduce) {
+  .fcx-ai-button, .fcx-ai-adopt { transition: none; }
+}

package/view.d.ts

@@ -25,3 +25,39 @@ export declare const CLS: Record<
   "root" | "head" | "button" | "adopt" | "body" | "answer" | "evidence" | "declined",
   string
 >;
+
+/** 프레임워크 중립 트리 노드 (0.3.0) — 어댑터는 이 트리의 인터프리터다 */
+export interface AiSuggestNode {
+  tag: string;
+  cls: string;
+  text?: string;
+  children?: AiSuggestNode[];
+  /** 추상 동작명 — 어댑터가 자기 이벤트 체계로 배선: "request" | "adopt" */
+  action?: "request" | "adopt";
+  type?: string;
+  disabled?: 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" | "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;