@things-factory/ai-assistant 10.1.27 → 10.1.29

package/dist-client/components/assistant-chat.d.ts

@@ -81,8 +81,10 @@ export declare class OxAssistantChat extends LitElement {
      * `@` mention 도메인 사용자 공급자 (선택). 호스트가 `domainUsersForMention` query 로 wrap.
      *
      * 호스트는 query 문자열을 받아 도메인 사용자 후보 (id/name/email) 배열을 돌려준다.
-     * 미설정 시 `@` popup 은 빈 결과 (사용자가 멘션 못 함). 멀티유저 환경 활성화 정책에 따라
-     * 호스트가 set 해야 활성화. async 가 자연스러우므로 Promise 반환 가능.
+     *
+     * **미설정이면 대화창이 이 패키지의 문(`domainUsersForMention`)에 직접 묻는다.** 예전에는 빈
+     * 결과였고, 그래서 앱 셋에서는 `@이름` 을 고를 수 없었다 — 멘션이 사람을 불러들이는 길을 세워도
+     * 부르는 자리가 없었다. 자기 목록을 따로 쓰는 호스트만 이것을 준다.
      */
     userProvider?: (query: string) => Promise<Array<{
         id: string;
@@ -114,22 +116,28 @@ export declare class OxAssistantChat extends LitElement {
     hostContext?: any;
     /** 코어 보드 편집 도구 사용 여부. 기본 true. 보드를 고칠 이유가 없는 면에서 false. */
     boardTools: boolean;
-    chatEndpoint: 'boardAIChat' | 'assistantChat';
-    /**
-     * Who the assistant is on this surface, in the host's words. Required by `assistantChat`; the
-     * board conversation carries its own persona on the server and ignores this.
-     */
+    chatEndpoint?: 'boardAIChat' | 'assistantChat';
     /**
      * What this conversation is — see `AssistantMode`.
      *
-     * A host that sets this does not set `systemPrompt`, `toolCategories`, `hostContext` or
-     * `chatEndpoint` separately, and does not rely on `registerChatDefaults` for its `@` and `/`
-     * lists: the mode carries all of them together, so they cannot disagree with each other.
+     * A host that sets this sets nothing else about the conversation: the persona, the tool
+     * categories, the model and the limits belong to the mode its app server registered, and what
+     * `@` and `/` offer comes from that same declaration, translated. They cannot disagree because
+     * there is one of them.
      *
-     * When `mode.id` changes the conversation on screen is closed and a new one begins.
+     * When `kind` or `target` changes the conversation on screen is closed and a new one begins.
      */
     mode?: AssistantMode;
-    systemPrompt?: string;
+    /**
+     * 이 화면이 보여 주는 것의 **종류** — `'board'`, `'space'`, `'station'`, `'figure'` (ADR-0072 A17 ①).
+     *
+     * `mode` 가 「지금 어느 대화인가」라면 이것은 「그 자리에 어떤 대화들이 설 수 있나」이다. 서버가
+     * `assistantModes(subject)` 로 답하고, 둘 이상이면 고르개가 뜬다. 하나면 고르개를 내지 않는다 —
+     * 고를 것이 없는 고르개는 자리만 차지한다.
+     *
+     * 화면이 이것을 안 주면 고르개는 없고 host 가 정한 대화 하나만 산다. 그것이 오늘까지의 모양이다.
+     */
+    subject?: string;
     /**
      * 라이브 상태를 다루는 대화면인가 — true 면 **첫 턴에 도구 호출을 강제**한다.
      *
@@ -152,7 +160,7 @@ export declare class OxAssistantChat extends LitElement {
         group?: string;
         properties?: Record<string, any>;
     }>;
-    placeholder: string;
+    placeholder?: string;
     private lines;
     private input;
     /**
@@ -263,6 +271,7 @@ export declare class OxAssistantChat extends LitElement {
      *  email 을 쓰는 이유: /auth/profile 이 항상 내려주는 로그인 식별자이고(비어 있지 않다),
      *  내부 관리키(User.id)를 클라이언트 판정에 의존하지 않기 위함. */
     private get _myEmail();
+    private get _myUserId();
     /** Mention popup — `#` (컴포넌트) / `@` (카탈로그) / `/` (slash) 트리거 시 활성.
      *  단일 popup 재사용 — mentionTrigger 로 활성 trigger 추적. */
     private mentionOpen;
@@ -291,6 +300,47 @@ export declare class OxAssistantChat extends LitElement {
     /** centerTo 디바운스 timer — arrow nav / hover 빠를 때 카메라 애니메이션 race 방지 */
     private centerDebounceTimer?;
     private get conversation();
+    /**
+     * What the server said this mode offers, in this person's language.
+     *
+     * Fetched when the mode changes and kept until the next one answers. Until it arrives the panel
+     * offers nothing rather than the list some other package registered globally.
+     */
+    private modeView?;
+    private modeViewToken;
+    /** 이 subject 에 설 수 있는 대화들 — 기본이 먼저. 하나뿐이면 고르개를 그리지 않는다. */
+    private modeChoices;
+    private modeChoicesToken;
+    /**
+     * 이 화면에 설 수 있는 대화를 서버에 묻는다.
+     *
+     * 화면이 종류 목록을 손에 들고 있으면, 대화를 하나 더 세운 날 그 화면만 모른 채로 남는다. 목록은
+     * 앱 서버의 선언에서 나온다(ADR-0072 A17 ①).
+     */
+    private loadModeChoices;
+    /**
+     * 사람이 다른 대화를 골랐다.
+     *
+     * 고른 것은 **이 subject 종류에 대해** 기억한다 — 보드를 열 때마다 저작 대화로 돌아가면, 현장을
+     * 물으려던 사람은 화면을 열 때마다 같은 손질을 다시 해야 한다. 기억은 이 브라우저에만 남는다
+     * (서버에 칸을 만들지 않는다 — A17 ①). 세션 자체는 자기가 어느 대화였는지 이미 안다.
+     */
+    private onModePick;
+    /**
+     * **고르는 것은 청하는 일이다** — `mode` 를 여기서 바꾸지 않는다.
+     *
+     * host 는 렌더마다 `mode` 를 다시 내려 준다. 패널이 자기 손으로 고쳐 두면 다음 렌더가 그것을 덮고,
+     * 더 나쁜 것은 host 가 **자기가 무엇을 열었는지 모르는 채로 남는다**는 것이다. host 는 대화의 세션을
+     * 대상별로 들고 있으므로, 대화가 바뀐 것을 모르면 앞 대화의 세션을 그대로 넘긴다 — 그러면 새 말이 앞
+     * 대화에 붙는다(2026-09-18 Figure 레인이 :3300 에서 본 것이 이것이다).
+     *
+     * 그래서 주인은 하나다: host 가 `mode` 를 갖고, 패널은 「이것으로 바꿔 달라」고 말한다. 기억은 패널이
+     * 진다(브라우저마다 다른 값이라 host 가 질 것이 아니다) — 기억한 것을 되살릴 때도 같은 청으로 나간다.
+     */
+    private askHostForMode;
+    /** 이 subject 에서 지난번에 고른 대화 — 없으면 undefined. */
+    private rememberedMode;
+    private loadModeView;
     private cachedCatalogCandidates;
     private cachedSlashCandidates;
     private rebuildMentionCaches;
@@ -301,6 +351,13 @@ export declare class OxAssistantChat extends LitElement {
     private userFetchToken;
     static styles: import("lit").CSSResult[];
     connectedCallback(): void;
+    /**
+     * 화면이 보여 주는 것의 종류가 바뀌었다 — 설 수 있는 대화를 다시 묻고, 지난번 고른 것을 되살린다.
+     *
+     * 되살리는 것은 **고른 대화**이지 세션이 아니다. 세션은 자기가 어느 대화였는지 이미 알고, 다른
+     * 대화로 가면 그때 새로 난다(ADR-0072 A17 ①).
+     */
+    private onSubjectChanged;
     updated(changed: Map<string, any>): void;
     disconnectedCallback(): void;
     private _startPresence;
@@ -325,6 +382,23 @@ export declare class OxAssistantChat extends LitElement {
     private _isOnline;
     private loadHistory;
     render(): import("lit-html").TemplateResult<1>;
+    /**
+     * 방에 말한다 — 어시스턴트는 답하지 않는다.
+     *
+     * 저장되는 대화가 있을 때만 할 수 있다. 세션이 없는 즉석 질문에는 「방」이 없다 — 그 자리에서
+     * 한 말은 누구에게도 남지 않는다.
+     */
+    private sayToRoom;
+    /**
+     * 보내기 전에 말한다 — 「이 사람은 이 대화에 들어옵니다」(ADR-0071 결정 1 ④).
+     *
+     * 멘션은 사람을 불러들인다. 누른 뒤에 알면 이미 들어와 있고, 협의의 공개 범위는 되돌리기 어려운
+     * 종류의 일이다. 그래서 **아직 보내지 않은 상태에서** 누가 들어오게 되는지 보인다.
+     *
+     * 초대할 수 없는 자리(보기 권한 · 아직 참여자가 아님)라면 그 사실을 말한다 — 눌렀는데 아무 일도
+     * 일어나지 않는 것이 가장 나쁘다.
+     */
+    private renderInviteNotice;
     private onKeyDown;
     /** input 이벤트 — value 즉시 반영 + popup 갱신은 150ms 디바운스 (F-Finder 와 동일).
      *  big board 에서 매 keystroke filter 비용 절감 + 한국어 IME 조합 중 깜빡임 완화. */
@@ -332,6 +406,12 @@ export declare class OxAssistantChat extends LitElement {
     /** 현재 cursor 위치를 보고 mention popup 활성/비활성 + 후보 갱신.
      *  `#` (컴포넌트) / `@` (카탈로그) / `/` (slash 템플릿) 한 번에 하나만 활성. */
     private refreshMentionPopup;
+    /**
+     * 호스트가 목록을 주지 않을 때 이 도메인의 사용자를 직접 묻는다.
+     *
+     * 실패는 빈 목록이다 — 멘션을 못 고르는 것이지 대화가 막힐 일은 아니다.
+     */
+    private fetchDomainUsers;
     /** `@` query 에 대한 userProvider 비동기 호출 — 응답 도착 시 popup 결과 갱신.
      *  race 방지: token 으로 최신 호출 식별 (늦게 도착한 응답 무시). */
     private refreshUserCandidatesAsync;
@@ -369,6 +449,29 @@ export declare class OxAssistantChat extends LitElement {
     private static readonly EXAMPLE_GROUPS;
     /** 보드의 세션 탭 — 다중 세션 활성화 시 패널 상단. host 가 sessions 비워두면 표시 X.
      *  레이블은 session.name 우선, 없으면 fallback "세션 N". */
+    /**
+     * 이 대화의 **주어** — 같은 화면 위에 두 대화가 설 때만 나온다(ADR-0072 A17 ①).
+     *
+     * 하나뿐이면 아무것도 그리지 않는다. 고를 것이 없는 고르개는 자리만 차지하고, 사람에게 「무언가
+     * 고를 것이 있다」는 잘못된 신호를 준다.
+     *
+     * ── 왜 탭 줄이 아닌가 (UX 레인, 2026-09-18) ───────────────────────────────
+     * 처음에는 칩 줄에 `role="tablist"` 를 달았다. 바로 아래가 세션 탭이고 그쪽도 tablist 라서, 화면
+     * 낭독기로 들으면 「탭 목록, 대화」 다음에 「탭 목록, Conversation history」 가 이어졌다 — 고르는
+     * 축이 둘인데 둘 다 「탭」이라고 말한다. 게다가 ARIA 탭은 좌우 화살표 이동과 `tabpanel` 이 함께
+     * 있어야 성립하고, 둘 다 없으면 낭독기는 「2 중 1번째 탭」이라 말하고 화살표는 아무 일도 안 한다.
+     *
+     * 무게도 다르다. 세션은 「어느 지난 대화냐」이고 모드는 「이 대화가 무엇에 대한 것이냐」이다. 같은
+     * 무게로 그리면 어느 쪽이 화제를 바꾸고 어느 쪽이 실타래를 바꾸는지 구별되지 않는다. 그래서 지금
+     * 대화가 제목 굵기로 서고, 바꿀 자리는 그 옆에 붙는다.
+     *
+     * ── 왜 도크 제목 줄로 안 올리나 (UX 레인 판정, 2026-09-18) ────────────────
+     * 도크 제목은 「지금 어디에 있나」(이 도형 · 이 현장 · 이 스테이션 화면)이고 이 줄은 「이 대화가
+     * 무엇에 대한 것이냐」이다. 대화의 주어는 대화 안에 있다. 그리고 세 도크가 각자 그리면 세 벌이 되고
+     * 그 세 벌은 갈린다 — `modeChoices` 를 아는 것도 여기다. 올리면 목록과 고른 것이 세 자리로 나갔다
+     * 돌아온다.
+     */
+    private renderModeSubject;
     private renderSessionTabs;
     /** C4 roster — 세션 참여자 + online 표시. 참여자 2명 미만이면 숨김(혼자면 의미 없음). */
     private renderRoster;
@@ -411,6 +514,13 @@ export declare class OxAssistantChat extends LitElement {
      * 실행 결과는 호스트가 **대화에 기록**한다 — 누가 무엇을 실행했는지가 협의 이력에 남아야 한다.
      */
     private renderProposals;
+    /**
+     * 눌린 카드가 말하는 것 — **호스트가 한 일**이고, 아직 모르면 모른다고 말한다.
+     *
+     * 예전에는 누른 순간 「실행됨」이었다. 09-18 트윈에서 아무 일도 일어나지 않은 채 「✓ 반영했습니다」가
+     * 떴다(ADR-0070 A12-a).
+     */
+    private proposalStateText;
     private onChoiceClick;
     /**
      * 제안 식별 키 — 같은 조치를 두 번 실행하지 않도록 **효과**(명령·대상·인자)로만 만든다.
@@ -424,7 +534,24 @@ export declare class OxAssistantChat extends LitElement {
      * 실행은 호스트가 한다 — 이 컴포넌트는 도메인(트윈 명령 채널)을 모른다.
      * 확인 대화·명령 전송·결과 기록은 호스트의 몫이고, 여기서는 중복 클릭만 막는다.
      */
+    /**
+     * 누른 시각 — 「보내는 중」 옆의 경과 시간용.
+     *
+     * 시간으로 실패를 판정하지 않는다(ADR-0070 A12-a 결정 ②). 아는 사실은 「아직 답을 받지 못했다」
+     * 하나이고, 시간이 지났다고 실패로 바꾸면 그것이 지어낸 원인이다.
+     */
+    private proposalSentAt;
+    private elapsedTimer?;
     private executeProposal;
+    /**
+     * 호스트가 무엇을 했는지 — 대화에 남은 `system` 행에서 읽는다(ADR-0070 A12-a 결정 ①).
+     *
+     * 카드가 자기 기억으로 상태를 들고 있으면 새로 고치는 순간 사라지고, 다른 창에서 실행한 것은
+     * 애초에 보이지 않는다. 그래서 상태의 자리는 이력이다.
+     */
+    private get proposalOutcomes();
+    /** 경과 시간을 보이는 동안에만 돈다 — 답이 오면 멈춘다. */
+    private _startElapsedTicker;
     /**
      * 접지 경고 — 답이 언급했지만 **근거에 없던** 대상을 알린다.
      *