@fcg-labs/cx-agent-hook 0.1.2 → 0.2.0

package/client.d.ts

@@ -54,12 +54,31 @@ export interface FeedbackInput {
   note?: string;
 }
 
+export interface AnswerStreamHandlers {
+  /** 텍스트 조각 — 누적(append) */
+  onDelta?(text: string): void;
+  /** 교정 재생성 시작 — 누적 전부 폐기 */
+  onRestart?(reasons: string[]): void;
+  onStage?(phase: string): void;
+  onFinal?(result: AnswerResult): void;
+  /** 외부 중단 (문의 전환 등) */
+  signal?: AbortSignal;
+  idleTimeoutMs?: number;
+  overallTimeoutMs?: number;
+}
+
 export declare class CxAgentClient {
   constructor(config: CxAgentConfig);
   getAnswer(
     inquiry: string,
     context?: Record<string, string>,
   ): Promise<AnswerResult>;
+  /** SSE 스트리밍 — 델타 콜백 + getAnswer 동형 결과. 404/405 는 비스트림 폴백. */
+  getAnswerStream(
+    inquiry: string,
+    context?: Record<string, string>,
+    handlers?: AnswerStreamHandlers,
+  ): Promise<AnswerResult>;
   sendFeedback(fb: FeedbackInput): Promise<FeedbackResult>;
   sent(answerId: number | string, finalText: string, agent?: string): Promise<FeedbackResult>;
   scored(answerId: number | string, score: number, agent?: string): Promise<FeedbackResult>;

package/client.js

@@ -21,6 +21,7 @@ const FEEDBACK_ACTIONS = new Set(["scored", "edited", "sent", "discarded"]);
 const PATHS = {
   platform: {
     answer: (d) => `/api/domains/${d}/answer`,
+    answerStream: (d) => `/api/domains/${d}/answer/stream`,
     feedback: (d) => `/api/domains/${d}/feedback`,
   },
   hub: {
@@ -31,12 +32,32 @@ const PATHS = {
     // 허브에 라우트가 생긴 뒤에도 SDK 가 그대로여서 hub 대상 getAnswer 가
     // HTTP 를 타보지도 못하고 unsupported_api 로 단락됐다 (2026-07-31 감사).
     answer: (d) => `/v1/domains/${d}/answer`,
+    answerStream: (d) => `/v1/domains/${d}/answer/stream`,
     feedback: (d) => `/v1/domains/${d}/feedback`,
     ingress: (d) => `/v1/domains/${d}/ingress`,
   },
   // platform 은 인그레스 API 미제공 (공장 큐레이션 파이프라인이 담당)
 };
 
+/**
+ * SSE 블록 1개 파싱 — "event: 이름" + "data: JSON 한 줄" 규약.
+ * 규약 밖 블록(주석·미지 이벤트·깨진 JSON)은 null — 스트림을 죽이지 않는다.
+ */
+function parseSSEBlock(block) {
+  let name = "";
+  let data = "";
+  for (const line of block.split("\n")) {
+    if (line.startsWith("event: ")) name = line.slice(7).trim();
+    else if (line.startsWith("data: ")) data = line.slice(6);
+  }
+  if (!name || !data) return null;
+  try {
+    return { name, data: JSON.parse(data) };
+  } catch {
+    return null;
+  }
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -220,6 +241,132 @@ export class CxAgentClient {
     }
   }
 
+  /**
+   * 서빙 답변 스트리밍 — 델타를 콜백으로 흘리고 getAnswer 와 동형의 결과로
+   * resolve 한다. throw 하지 않는다.
+   *
+   * 타임아웃 계단(정본): 서버 LLM 60s×2 < 허브 180s < 여기 overall 190s.
+   * idle 90s 는 침묵 구간(콜드 검색+첫 토큰, 교정 재시작 후 첫 토큰)을 덮는다 —
+   * 더 짧으면 정상 생성을 오탐으로 자른다 (30s 시절 사고의 재판 금지).
+   *
+   * @param {string} inquiry
+   * @param {Record<string,string>} [context]
+   * @param {object} [handlers]
+   * @param {(text:string)=>void} [handlers.onDelta]  텍스트 조각 (append)
+   * @param {(reasons:string[])=>void} [handlers.onRestart] 교정 재생성 시작 —
+   *   지금까지의 누적을 전부 버릴 것
+   * @param {(phase:string)=>void} [handlers.onStage] retrieving|generating|correcting
+   * @param {(result:object)=>void} [handlers.onFinal]
+   * @param {AbortSignal} [handlers.signal] 외부 중단 (문의 전환 등)
+   * @param {number} [handlers.idleTimeoutMs=90000]
+   * @param {number} [handlers.overallTimeoutMs=190000]
+   */
+  async getAnswerStream(inquiry, context, {
+    onDelta, onRestart, onStage, onFinal, signal,
+    idleTimeoutMs = 90000, overallTimeoutMs = 190000,
+  } = {}) {
+    const fail = (reason, raw = {}) => ({
+      ok: false, answered: false, answer: "", answerId: null,
+      evidence: [], declinedReason: reason, raw,
+    });
+    const target = this._target("answer");
+    const streamPath = PATHS[target.api] && PATHS[target.api].answerStream;
+    if (!streamPath) {
+      this.onError(
+        new Error("답변 생성 대상이 설정되지 않았습니다 (answer.baseUrl 확인)"),
+        { op: "getAnswerStream" },
+      );
+      return fail("unsupported_api");
+    }
+    const body = { inquiry };
+    const ctx = normalizeContext(context);
+    if (ctx) body.context = ctx;
+
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    if (signal) {
+      if (signal.aborted) return fail("network_error");
+      signal.addEventListener("abort", abort, { once: true });
+    }
+    const overallTimer = setTimeout(abort, overallTimeoutMs);
+    let idleTimer = setTimeout(abort, idleTimeoutMs);
+    const bumpIdle = () => {
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(abort, idleTimeoutMs);
+    };
+    try {
+      const res = await this.fetchImpl(target.baseUrl + streamPath(this.domain), {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${target.token}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      if (res.status === 404 || res.status === 405) {
+        // 구 서버(스트림 라우트 이전) 혼재 배포 — 비스트림으로 폴백.
+        // 델타 없이 완성본이 한 번에 오지만 기능은 산다 (배포 순서 안전판).
+        return await this.getAnswer(inquiry, context);
+      }
+      if (res.status !== 200) {
+        const data = await res.json().catch(() => ({}));
+        return fail((data && data.error) || `http_${res.status}`, data);
+      }
+      const reader = res.body.getReader();
+      // {stream:true} 필수 — 한글 3바이트 문자가 청크 경계에서 잘리면
+      // 이것 없이는 U+FFFD 로 깨진다 (한국어 스트림의 최다 빈도 버그).
+      const decoder = new TextDecoder("utf-8");
+      let buffer = "";
+      let final = null;
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        bumpIdle();
+        buffer += decoder.decode(value, { stream: true });
+        let sep;
+        while ((sep = buffer.indexOf("\n\n")) !== -1) {
+          const event = parseSSEBlock(buffer.slice(0, sep));
+          buffer = buffer.slice(sep + 2);
+          if (!event) continue;
+          if (event.name === "delta") {
+            if (onDelta) onDelta(String(event.data.text || ""));
+          } else if (event.name === "restart") {
+            if (onRestart) onRestart(event.data.reasons || []);
+          } else if (event.name === "stage") {
+            if (onStage) onStage(String(event.data.phase || ""));
+          } else if (event.name === "final") {
+            final = event.data;
+          }
+        }
+      }
+      if (!final) {
+        // final 없이 끊김 = 절단 (허브 상한·네트워크) — 부분 텍스트는 무효다.
+        this.onError(new Error("스트림이 final 없이 종료됐습니다"),
+                     { op: "getAnswerStream" });
+        return fail("network_error");
+      }
+      const result = {
+        ok: true,
+        answered: Boolean(final.answered),
+        answer: final.answer || "",
+        answerId: final.answer_id ?? null,
+        evidence: final.evidence || [],
+        declinedReason: final.declined_reason || "",
+        raw: final,
+      };
+      if (onFinal) onFinal(result);
+      return result;
+    } catch (err) {
+      this.onError(err, { op: "getAnswerStream" });
+      return fail("network_error");
+    } finally {
+      clearTimeout(overallTimer);
+      clearTimeout(idleTimer);
+      if (signal) signal.removeEventListener("abort", abort);
+    }
+  }
+
   /**
    * 교정 후킹 — CS팀 업무를 막지 않는다: throw 없이 재시도 후 결과 보고.
    * @param {object} fb

package/index.d.ts

@@ -42,6 +42,17 @@ export interface CxHook {
     context?: Record<string, string>,
   ): Promise<AnswerResult>;
 
+  /** 초안 직주입 스트리밍 — 에디터 접근자만 배선하면 나머지 판단은 훅 소유.
+   * 성공 시 자동 채택(noteAdopted) — answerSent 귀속이 그대로 성립한다. */
+  composeDraft(opts: {
+    inquiry: string;
+    context?: Record<string, string>;
+    getDraft?: () => string;
+    setDraft: (text: string) => void;
+    setStatus?: (text: string) => void;
+    confirmOverwrite?: () => boolean;
+  }): { promise: Promise<AnswerResult>; abort: () => void };
+
   /** 제안을 에디터에 넣었다 (패널이 부른다) */
   noteAdopted(answerId: number | string | null): void;
   /** 채택 기록 폐기 — 문의 전환 시 */

package/index.js

@@ -105,6 +105,87 @@ export function createCxHook(config = {}) {
       return client.getAnswer(inquiry, context);
     },
 
+    /** 초안 직주입 스트리밍 — 답변 에디터에 AI 초안을 직접 흘려 쓴다.
+     *
+     * 패널·채택 버튼 없는 흐름의 정본이다: 소비처는 에디터 접근자(getDraft·
+     * setDraft)와 상태 표시(setStatus)만 배선하고, 나머지 제품 판단 —
+     * 덮어쓰기 확인, 교정 재시작 처리, 실패 시 원복, 문구, **자동 채택 귀속**
+     * (직주입 = 채택이므로 성공 시 noteAdopted 를 훅이 스스로 부른다) — 은
+     * 전부 여기 있다. answerSent 의 consume 의미론은 그대로다.
+     *
+     * @param {object} opts
+     * @param {string} opts.inquiry
+     * @param {Record<string,string>} [opts.context]
+     * @param {()=>string} [opts.getDraft] 현재 초안 (덮어쓰기 가드용)
+     * @param {(text:string)=>void} opts.setDraft 초안 전체 치환 (누적 스냅샷)
+     * @param {(text:string)=>void} [opts.setStatus] 한 줄 상태 ("" = 지움)
+     * @param {()=>boolean} [opts.confirmOverwrite] 초안이 비어있지 않을 때 확인
+     * @returns {{promise: Promise<object>, abort: ()=>void}}
+     */
+    composeDraft({ inquiry, context, getDraft, setDraft, setStatus,
+                   confirmOverwrite } = {}) {
+      const status = (text) => { if (setStatus) setStatus(text || ""); };
+      const noop = { promise: Promise.resolve(NOT_CONFIGURED), abort: () => {} };
+      if (!client || !inquiry || typeof setDraft !== "function") {
+        status(textOf(messages, "not_configured"));
+        return noop;
+      }
+      const existing = typeof getDraft === "function"
+        ? String(getDraft() || "") : "";
+      if (existing.trim() && !(confirmOverwrite && confirmOverwrite())) {
+        // 상담사가 쓰던 초안이 우선한다 — 조용히 덮지 않는다.
+        return { promise: Promise.resolve({ ...NOT_CONFIGURED, declinedReason: "" }),
+                 abort: () => {} };
+      }
+      // 새 스트림 = 이전 채택 무효 (문의가 같아도 초안이 바뀐다)
+      adoptedAnswerId = null;
+
+      const controller = new AbortController();
+      let accumulated = "";
+      let pending = null;
+      const flushDraft = () => { pending = null; setDraft(accumulated); };
+      const queueDraft = () => {
+        // trailing 스로틀 — 청크마다 리렌더하면 큰 화면이 버벅인다
+        if (pending === null) pending = setTimeout(flushDraft, 80);
+      };
+      const clearPending = () => {
+        if (pending !== null) { clearTimeout(pending); pending = null; }
+      };
+
+      status(messages.ui_requesting);
+      setDraft("");
+      const promise = client.getAnswerStream(inquiry, context, {
+        signal: controller.signal,
+        onDelta(text) { accumulated += text; queueDraft(); },
+        onRestart() {
+          // 계약 위반 교정 — 지금까지 보인 초안은 폐기본이다
+          clearPending();
+          accumulated = "";
+          setDraft("");
+          status(messages.ui_correcting);
+        },
+        onStage(phase) {
+          if (phase === "generating") status(messages.ui_requesting);
+        },
+      }).then((result) => {
+        clearPending();
+        if (result.answered) {
+          setDraft(result.answer);          // 정본으로 확정 (strip 반영)
+          adoptedAnswerId = result.answerId ?? null;
+          status("");
+        } else {
+          // 실패·거절 — 미완성 텍스트를 에디터에 남기지 않고 원래 초안 복원
+          setDraft(existing);
+          status(textOf(messages, result.declinedReason || "unknown"));
+        }
+        return result;
+      });
+      return {
+        promise,
+        abort: () => { clearPending(); controller.abort(); },
+      };
+    },
+
     /** 제안을 에디터에 넣었다 (패널이 부른다) */
     noteAdopted(answerId) {
       adoptedAnswerId = answerId || null;

package/locales.js

@@ -30,6 +30,8 @@ const en = {
   ui_requesting: "Generating…",
   ui_adopt: "Insert into editor",
   ui_evidence: "Sources",
+  ui_correcting: "Fixing phrasing — rewriting…",
+  ui_overwrite_confirm: "Replace your current draft with the AI draft?",
   // 거절·오류 사유
   not_configured: "AI reply suggestions are not connected yet.",
   unsupported_api: "AI reply suggestions are not connected yet.",
@@ -54,6 +56,8 @@ const ko = {
   ui_requesting: "제안 생성 중...",
   ui_adopt: "에디터에 넣기",
   ui_evidence: "근거",
+  ui_correcting: "표현 교정 중 — 다시 쓰는 중...",
+  ui_overwrite_confirm: "작성 중인 답변을 지우고 AI 초안으로 바꿀까요?",
   not_configured: "AI 답변 제안이 아직 연결되지 않았습니다.",
   unsupported_api: "AI 답변 제안이 아직 연결되지 않았습니다.",
   answer_disabled: "AI 답변 제안은 아직 켜지지 않았습니다. 문의·답변 수집만 진행 중입니다.",
@@ -73,6 +77,8 @@ const ja = {
   ui_requesting: "生成中...",
   ui_adopt: "エディタに挿入",
   ui_evidence: "根拠",
+  ui_correcting: "表現を修正中 — 書き直しています…",
+  ui_overwrite_confirm: "作成中の回答を消してAI下書きに置き換えますか？",
   not_configured: "AI 返信案はまだ接続されていません。",
   unsupported_api: "AI 返信案はまだ接続されていません。",
   answer_disabled: "AI 返信案はまだ有効になっていません。問い合わせの収集のみ実行中です。",
@@ -92,6 +98,8 @@ const zhTW = {
   ui_requesting: "產生中...",
   ui_adopt: "插入編輯器",
   ui_evidence: "依據",
+  ui_correcting: "正在修正表述 — 重新撰寫中…",
+  ui_overwrite_confirm: "要清除目前草稿並以 AI 草稿取代嗎？",
   not_configured: "AI 回覆建議尚未連接。",
   unsupported_api: "AI 回覆建議尚未連接。",
   answer_disabled: "AI 回覆建議尚未啟用，目前僅進行問題收集。",

package/package.json

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