@things-factory/ai-assistant 10.1.24 → 10.1.25

package/client/components/assistant-chat.ts

@@ -7,8 +7,8 @@
  *   - scopes / knownTypes / categories: 도메인 컨텍스트
  *
  * 출력 (이벤트):
- *   - `board-edit-patch` { detail: { patch, summary, confidence, patchId } }
- *     호스트가 받아서 보드 모델에 적용 (applyBoardEditPatch helper).
+ *   - `scene-edit-patch` { detail: { patch, summary, confidence, patchId } }
+ *     호스트가 받아서 보드 모델에 적용 (applyScenePatch from @operato/scene-ops).
  *   - `chat-followup` { detail: { question } }
  *
  * 모드 전환은 컨테이너 (워크스페이스) 의 책임. 이 컴포넌트는 자체로 풀 채팅 UX.
@@ -59,6 +59,7 @@ import {
  * 뜨지 않는 것이 맞다.
  */
 import { chatDefaults } from './chat-defaults.js'
+import { isDifferentConversation, resolveConversation, type AssistantMode } from './assistant-mode.js'
 import { availableTriggers, type TriggerChip } from './chat-triggers.js'
 
 interface ChatLine {
@@ -365,6 +366,18 @@ export class OxAssistantChat extends LitElement {
    * 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.
    */
+  /**
+   * 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.
+   *
+   * When `mode.id` changes the conversation on screen is closed and a new one begins.
+   */
+  @property({ attribute: false })
+  mode?: AssistantMode
+
   @property({ type: String, attribute: 'system-prompt' })
   systemPrompt?: string
 
@@ -594,7 +607,7 @@ export class OxAssistantChat extends LitElement {
       The screen still shows nothing either way. There is no sentence to show, and inventing one is
       what this whole correction removed.
     */
-    if (!chatDefaults.stagedNoticeKey && !OxAssistantChat.warnedMissingStagedNotice) {
+    if (!this.conversation.stagedNoticeKey && !OxAssistantChat.warnedMissingStagedNotice) {
       OxAssistantChat.warnedMissingStagedNotice = true
       console.warn(
         '[assistant-chat] a host reported a proposal staged but registered no `stagedNoticeKey`, ' +
@@ -692,12 +705,40 @@ export class OxAssistantChat extends LitElement {
   /** centerTo 디바운스 timer — arrow nav / hover 빠를 때 카메라 애니메이션 race 방지 */
   private centerDebounceTimer?: ReturnType<typeof setTimeout>
 
-  /** Default 카탈로그 후보 캐시 — chat panel mount 시 1회 빌드 */
+  /*
+   * ── What this conversation is, resolved ──────────────────────────────────────────────
+   *
+   * A mode answers first. A host that has not declared one keeps the separate properties and
+   * the global defaults it had before, which is what every consumer written before modes does.
+   */
+  private get conversation() {
+    return resolveConversation(
+      this.mode,
+      {
+        systemPrompt: this.systemPrompt,
+        toolCategories: this.toolCategories,
+        hostContext: this.hostContext,
+        chatEndpoint: this.chatEndpoint
+      },
+      chatDefaults
+    )
+  }
+
+  /*
+   * The `@` and `/` candidates, built once per mode.
+   *
+   * These were built at field initialisation, which meant a host could not change what the
+   * panel offers without replacing the element. A mode change rebuilds them below.
+   */
   private cachedCatalogCandidates: MentionCandidate[] = buildCatalogCandidates(chatDefaults.catalogEntries)
 
-  /** Default slash template 후보 캐시 — chat panel mount 시 1회 빌드 */
   private cachedSlashCandidates: MentionCandidate[] = buildSlashCandidates(chatDefaults.slashTemplates)
 
+  private rebuildMentionCaches() {
+    this.cachedCatalogCandidates = buildCatalogCandidates(this.conversation.catalogEntries)
+    this.cachedSlashCandidates = buildSlashCandidates(this.conversation.slashTemplates)
+  }
+
   /** `@` 마지막 query 의 도메인 사용자 후보 캐시 — userProvider 응답 도착 시 갱신.
    *  query 별 캐시가 아니라 단순 "최근 결과" — async race 회피. */
   private cachedUserCandidates: MentionCandidate[] = []
@@ -2214,6 +2255,36 @@ export class OxAssistantChat extends LitElement {
       this.send()
     }
 
+    /*
+     * The subject changed, so the conversation is over.
+     *
+     * A conversation about station 3 is not a conversation about station 7. Leaving the old one
+     * on screen means the user reads an answer about a screen they are no longer looking at,
+     * and every host that met this wrote its own guard: plant re-checked the context on each
+     * send and threw when it had moved, twin closed its session when the anchor changed. The
+     * mode carries an id, so the component can do it once, here.
+     *
+     * The host still owns `sessionId`; it hears `assistant-mode-changed` and decides whether
+     * this subject gets a stored session of its own.
+     */
+    if (changed.has('mode') && isDifferentConversation(changed.get('mode'), this.mode)) {
+      this.rebuildMentionCaches()
+      this.lines = []
+      this.pickedMentions.clear()
+      this.pickedUserMentions.clear()
+      this.cachedUserCandidates = []
+      this.errorMessage = undefined
+      this.input = ''
+      this._seenMessageIds.clear()
+      this.dispatchEvent(
+        new CustomEvent('assistant-mode-changed', {
+          detail: { mode: this.mode },
+          bubbles: true,
+          composed: true
+        })
+      )
+    }
+
     if (changed.has('sessionId') && this.adoptingSession) {
       this.adoptingSession = false
       this._startPresence()
@@ -2815,7 +2886,7 @@ export class OxAssistantChat extends LitElement {
 
   private dispatchActions(actions: any[]) {
     this.dispatchEvent(
-      new CustomEvent('board-action-execute', {
+      new CustomEvent('scene-action-execute', {
         detail: { actions, sessionId: this.sessionId },
         bubbles: true,
         composed: true
@@ -2946,7 +3017,7 @@ export class OxAssistantChat extends LitElement {
     return availableTriggers({
       hasMentionableThings: !!(this.boardProvider || this.currentBoard || this.knownTypes?.length),
       hasSession: !!this.sessionId,
-      slashTemplateCount: chatDefaults.slashTemplates.length
+      slashTemplateCount: this.conversation.slashTemplates.length
     })
   }
 
@@ -3082,8 +3153,8 @@ export class OxAssistantChat extends LitElement {
           <span class="badge">${i18next.t('ai-assistant.label.korean-supported')}</span>
           <span class="badge">${i18next.t('ai-assistant.label.multi-command')}</span>
           <span class="badge">${i18next.t('ai-assistant.label.review-able')}</span>
-          ${chatDefaults.footerNoticeKey
-            ? html`<br />${i18next.t(chatDefaults.footerNoticeKey)}`
+          ${this.conversation.footerNoticeKey
+            ? html`<br />${i18next.t(this.conversation.footerNoticeKey)}`
             : ''}
         </div>
       </div>
@@ -3242,7 +3313,7 @@ export class OxAssistantChat extends LitElement {
             to live here named a 3D modeller's operations in hardcoded Korean, and it reached the
             plant and twin chats too.
           */
-          const rawChoices: any[] = Array.isArray(p.choices) ? p.choices : (chatDefaults.proposalChoices ?? [])
+          const rawChoices: any[] = Array.isArray(p.choices) ? p.choices : this.conversation.proposalChoices
 
           return html`
             <div class="proposal ${sent ? 'sent' : ''}">
@@ -3271,10 +3342,10 @@ export class OxAssistantChat extends LitElement {
                   This badge used to read "there are chips" as "the model is in the 3D viewer" and
                   say so, in a component that plant and twin also use.
                 */ ''}
-              ${this.stagedProposals.has(key) && chatDefaults.stagedNoticeKey ? html`
+              ${this.stagedProposals.has(key) && this.conversation.stagedNoticeKey ? html`
                 <span class="staged-badge">
                   <md-icon>check_circle</md-icon>
-                  <span>${i18next.t(chatDefaults.stagedNoticeKey)}</span>
+                  <span>${i18next.t(this.conversation.stagedNoticeKey!)}</span>
                 </span>
               ` : nothing}
             </div>
@@ -3668,7 +3739,7 @@ export class OxAssistantChat extends LitElement {
     let requestBase: any
     try {
       const provided = this.contextProvider?.() || {}
-      requestContext = structuredClone({ systemPrompt: this.systemPrompt, hostContext: this.hostContext, ...provided })
+      requestContext = structuredClone({ systemPrompt: this.conversation.systemPrompt, hostContext: this.conversation.hostContext, ...provided })
       liveBoard = structuredClone(this.boardProvider ? this.boardProvider() : this.currentBoard)
       requestBase = { version: 1, sessionId: this.sessionId, hostContext: requestContext.hostContext,
         modelFingerprint: assistantModelFingerprint(liveBoard) }
@@ -3745,7 +3816,7 @@ export class OxAssistantChat extends LitElement {
       // 라이브 보드 우선 — 호스트의 캔버스가 사용자 수작업 편집을 들고 있을 수 있음.
       // boardProvider 가 있으면 send 시점에 그것을 pull, 없으면 정적 currentBoard.
       // mentions 는 위에서 이미 계산해 user line 에 thread — 그대로 mutation 입력으로 재사용.
-      const neutral = this.chatEndpoint === 'assistantChat'
+      const neutral = this.conversation.chatEndpoint === 'assistantChat'
       const result = await client.mutate({
         mutation: neutral ? ASSISTANT_CHAT_MUTATION : BOARD_AI_CHAT_MUTATION,
         variables: {
@@ -3756,7 +3827,7 @@ export class OxAssistantChat extends LitElement {
                 systemPrompt: requestContext.systemPrompt!,
                 truncateAfterMessageId: this._truncateAfterId,
                 hostContext: requestContext.hostContext,
-                toolCategories: this.toolCategories,
+                toolCategories: this.conversation.toolCategories,
                 requireGroundingTools: this.requireGroundingTools
               })
             : buildChatMutationInput({
@@ -3766,7 +3837,7 @@ export class OxAssistantChat extends LitElement {
                 scopes: this.scopes,
                 truncateAfterMessageId: this._truncateAfterId,
                 hostContext: requestContext.hostContext,
-                toolCategories: this.toolCategories,
+                toolCategories: this.conversation.toolCategories,
                 boardTools: this.boardTools,
                 requireGroundingTools: this.requireGroundingTools,
                 knownTypes: this.knownTypes,
@@ -3821,7 +3892,7 @@ export class OxAssistantChat extends LitElement {
       // 호스트로 patch 이벤트 전파
       if (out.patch) {
         this.dispatchEvent(
-          new CustomEvent('board-edit-patch', {
+          new CustomEvent('scene-edit-patch', {
             detail: {
               patch: out.patch,
               requestBase,
@@ -3838,7 +3909,7 @@ export class OxAssistantChat extends LitElement {
       // 호스트로 ephemeral scene 조작 actions 전파 (selection / view / mode)
       if (Array.isArray(out.actions) && out.actions.length > 0) {
         this.dispatchEvent(
-          new CustomEvent('board-action-execute', {
+          new CustomEvent('scene-action-execute', {
             detail: { actions: out.actions, sessionId: out.sessionId, requestBase },
             bubbles: true,
             composed: true

package/client/components/assistant-mode.test.ts

@@ -0,0 +1,82 @@
+/*
+ * A mode is one value, and the point of it is that the parts of a conversation cannot
+ * disagree with each other.
+ *
+ * The defect this guards against shipped: a screen whose systemPrompt said "you do not edit
+ * boards here" offered `/add-monitor` in the same panel, because the prompt was an element
+ * property and the slash list was a module global. Any resolution that lets a mode supply one
+ * of them while something else supplies the other brings it back.
+ */
+import { isDifferentConversation, resolveConversation, type AssistantMode } from './assistant-mode'
+
+const MODE: AssistantMode = {
+  id: 'twin:space:S-12',
+  systemPrompt: 'You are looking at one space. You do not edit boards here.',
+  toolCategories: ['twin'],
+  hostContext: { spaceId: 'S-12' },
+  slashTemplates: [{ name: 'status', template: '이 공간의 지금 상태를 요약해줘' }]
+}
+
+const HOST_PROPERTIES = {
+  systemPrompt: 'a prompt the host set the old way',
+  toolCategories: ['board-ai'],
+  hostContext: { boardId: 'B-1' },
+  chatEndpoint: 'boardAIChat' as const
+}
+
+const GLOBAL_DEFAULTS = {
+  catalogEntries: [{ type: 'rect' }],
+  slashTemplates: [{ name: 'add-monitor', template: '모니터를 추가해줘' }],
+  footerNoticeKey: 'text.previewed-on-the-board'
+}
+
+describe('resolveConversation', () => {
+  test('a mode answers before the host properties it overlaps', () => {
+    const c = resolveConversation(MODE, HOST_PROPERTIES, GLOBAL_DEFAULTS)
+    expect(c.systemPrompt).toBe(MODE.systemPrompt)
+    expect(c.toolCategories).toEqual(['twin'])
+    expect(c.hostContext).toEqual({ spaceId: 'S-12' })
+  })
+
+  test('a mode answers before the global defaults — the prompt and the slash list cannot disagree', () => {
+    const c = resolveConversation(MODE, HOST_PROPERTIES, GLOBAL_DEFAULTS)
+    expect(c.slashTemplates).toEqual(MODE.slashTemplates)
+    /* A mode that says it does not edit boards must not offer a board edit. */
+    expect(JSON.stringify(c.slashTemplates)).not.toContain('add-monitor')
+  })
+
+  test('what a mode leaves out still comes from the defaults', () => {
+    const c = resolveConversation(MODE, HOST_PROPERTIES, GLOBAL_DEFAULTS)
+    expect(c.catalogEntries).toEqual(GLOBAL_DEFAULTS.catalogEntries)
+    expect(c.footerNoticeKey).toBe(GLOBAL_DEFAULTS.footerNoticeKey)
+  })
+
+  test('a host with no mode gets exactly what it had before modes existed', () => {
+    const c = resolveConversation(undefined, HOST_PROPERTIES, GLOBAL_DEFAULTS)
+    expect(c.systemPrompt).toBe(HOST_PROPERTIES.systemPrompt)
+    expect(c.toolCategories).toEqual(HOST_PROPERTIES.toolCategories)
+    expect(c.slashTemplates).toEqual(GLOBAL_DEFAULTS.slashTemplates)
+  })
+
+  test('nothing anywhere resolves to empty lists and the board endpoint, never undefined', () => {
+    const c = resolveConversation(undefined, {}, {})
+    expect(c.catalogEntries).toEqual([])
+    expect(c.slashTemplates).toEqual([])
+    expect(c.proposalChoices).toEqual([])
+    expect(c.chatEndpoint).toBe('boardAIChat')
+  })
+})
+
+describe('isDifferentConversation', () => {
+  const station3: AssistantMode = { id: 'plant:station:3' }
+
+  test('a different subject ends the conversation', () => {
+    expect(isDifferentConversation(station3, { id: 'plant:station:7' })).toBe(true)
+    expect(isDifferentConversation(undefined, station3)).toBe(true)
+  })
+
+  test('rewording the same subject does not', () => {
+    expect(isDifferentConversation(station3, { ...station3, systemPrompt: 'reworded' })).toBe(false)
+    expect(isDifferentConversation(undefined, undefined)).toBe(false)
+  })
+})

package/client/components/assistant-mode.ts

@@ -0,0 +1,124 @@
+/**
+ * A mode is what a conversation *is*: who the assistant is, what it can do, what the talk is
+ * about, what it offers to start with, and when it is over.
+ *
+ * Those five used to be four separate properties on the chat element plus one global registry,
+ * and every host wired them one at a time. Separate means they can disagree, and they did: a
+ * screen whose `systemPrompt` said "you do not edit boards here" offered `/add-monitor` in the
+ * same panel, because the prompt was a property and the slash list was global.
+ *
+ * So a host declares one value and hands it over. What cannot be split cannot fall out of step.
+ *
+ * ```ts
+ * const SPACE_MODE = (spaceId: string): AssistantMode => ({
+ *   id: `twin:space:${spaceId}`,
+ *   systemPrompt: '...',
+ *   toolCategories: ['twin'],
+ *   hostContext: { spaceId },
+ *   slashTemplates: TWIN_SLASH_TEMPLATES
+ * })
+ *
+ * html`<ox-assistant-chat .mode=${SPACE_MODE(this.spaceId)}></ox-assistant-chat>`
+ * ```
+ */
+export interface AssistantMode {
+  /**
+   * What this conversation is about, as a string the host can compare.
+   *
+   * **The conversation's lifetime hangs on this.** When it changes, the chat closes what is on
+   * screen and starts again — because a conversation about station 3 is not a conversation
+   * about station 7, and leaving the old one up means the user reads an answer about a screen
+   * they are no longer looking at.
+   *
+   * Hosts built this by hand before, each in their own way: plant kept a module-global registry
+   * with subscribers and re-checked the context on every send, twin closed its session when the
+   * anchor moved. Both were writing the same guard around the same absence.
+   *
+   * Include whatever makes the subject specific — `twin:space:S-12`, `plant:station:3`.
+   */
+  id: string
+
+  /** Who the assistant is here, and what it must not claim to do. */
+  systemPrompt?: string
+
+  /** Which tool categories the server may expose for this conversation. */
+  toolCategories?: string[]
+
+  /** What the host knows about the subject; travels with each request. */
+  hostContext?: any
+
+  /** Which server-side chat entry point answers. */
+  chatEndpoint?: 'boardAIChat' | 'assistantChat'
+
+  /** What `@` offers. */
+  catalogEntries?: any[]
+
+  /**
+   * What `/` offers.
+   *
+   * These are sentences a person could have typed, not tool names — "이 공간의 지금 상태를
+   * 요약해줘" cannot be generated from `summarizeStatus`. But **a mode must not offer work it
+   * cannot do**: everything here should be answerable by the tools `toolCategories` opens.
+   */
+  slashTemplates?: any[]
+
+  /** The i18n key for the line under an empty conversation. */
+  footerNoticeKey?: string
+
+  /** Follow-up chips for a proposal that arrived without its own. */
+  proposalChoices?: any[]
+
+  /** The i18n key for the line shown once the host reports a proposal staged. */
+  stagedNoticeKey?: string
+}
+
+/** True when these two describe different conversations, so the old one should be closed. */
+export function isDifferentConversation(a?: AssistantMode, b?: AssistantMode): boolean {
+  return (a?.id ?? '') !== (b?.id ?? '')
+}
+
+/** Everything a conversation needs, after the mode, the host's own properties and the
+ *  registered defaults have been reconciled. */
+export interface ConversationSettings {
+  systemPrompt?: string
+  toolCategories?: string[]
+  hostContext?: any
+  chatEndpoint: 'boardAIChat' | 'assistantChat'
+  catalogEntries: any[]
+  slashTemplates: any[]
+  footerNoticeKey?: string
+  proposalChoices: any[]
+  stagedNoticeKey?: string
+}
+
+/**
+ * Reconcile the three places a setting can come from.
+ *
+ * **The mode answers first, as a whole.** Then the host's own properties, then whatever was
+ * registered globally. The order matters in one direction only: a host that declares a mode
+ * must not have half of its conversation decided somewhere else, which is the failure this
+ * type exists to remove.
+ *
+ * A host that declares no mode gets exactly what it got before modes existed — its own
+ * properties, falling back to the registered defaults.
+ */
+export function resolveConversation(
+  mode: AssistantMode | undefined,
+  own: Partial<ConversationSettings>,
+  defaults: Partial<ConversationSettings>
+): ConversationSettings {
+  const pick = <K extends keyof ConversationSettings>(key: K): ConversationSettings[K] =>
+    (mode as any)?.[key] ?? (own as any)[key] ?? (defaults as any)[key]
+
+  return {
+    systemPrompt: pick('systemPrompt'),
+    toolCategories: pick('toolCategories'),
+    hostContext: pick('hostContext'),
+    chatEndpoint: pick('chatEndpoint') ?? 'boardAIChat',
+    catalogEntries: pick('catalogEntries') ?? [],
+    slashTemplates: pick('slashTemplates') ?? [],
+    footerNoticeKey: pick('footerNoticeKey'),
+    proposalChoices: pick('proposalChoices') ?? [],
+    stagedNoticeKey: pick('stagedNoticeKey')
+  }
+}

package/client/index.ts

@@ -5,12 +5,12 @@
  */
 export * from './components/assistant-chat.js'
 export * from './components/chat-defaults.js'
+export * from './components/assistant-mode.js'
 export * from './components/markdown.js'
 export * from './components/chat-echo-dedup.js'
 export * from './components/chat-input-builder.js'
 export * from './components/mention-popup.js'
 export * from './components/mention-popup-helpers.js'
-export * from './utils/board-edit-patch.js'
 export * from './utils/assistant-session-controller.js'
 export * from './utils/assistant-session-transport.js'
 export * from './components/assistant-session-toolbar.js'

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

@@ -7,8 +7,8 @@
  *   - scopes / knownTypes / categories: 도메인 컨텍스트
  *
  * 출력 (이벤트):
- *   - `board-edit-patch` { detail: { patch, summary, confidence, patchId } }
- *     호스트가 받아서 보드 모델에 적용 (applyBoardEditPatch helper).
+ *   - `scene-edit-patch` { detail: { patch, summary, confidence, patchId } }
+ *     호스트가 받아서 보드 모델에 적용 (applyScenePatch from @operato/scene-ops).
  *   - `chat-followup` { detail: { question } }
  *
  * 모드 전환은 컨테이너 (워크스페이스) 의 책임. 이 컴포넌트는 자체로 풀 채팅 UX.
@@ -19,6 +19,7 @@ import { type AssistantRequestContext } from '../utils/assistant-request-context
 import { LitElement } from 'lit';
 import './mention-popup.js';
 import { type FilterResult } from './mention-popup.js';
+import { type AssistantMode } from './assistant-mode.js';
 export interface ChatAttachment {
     id: string;
     file: File;
@@ -118,6 +119,16 @@ export declare class OxAssistantChat extends LitElement {
      * 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.
      */
+    /**
+     * 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.
+     *
+     * When `mode.id` changes the conversation on screen is closed and a new one begins.
+     */
+    mode?: AssistantMode;
     systemPrompt?: string;
     /**
      * 라이브 상태를 다루는 대화면인가 — true 면 **첫 턴에 도구 호출을 강제**한다.
@@ -279,10 +290,10 @@ export declare class OxAssistantChat extends LitElement {
     private inputDebounceTimer?;
     /** centerTo 디바운스 timer — arrow nav / hover 빠를 때 카메라 애니메이션 race 방지 */
     private centerDebounceTimer?;
-    /** Default 카탈로그 후보 캐시 — chat panel mount 시 1회 빌드 */
+    private get conversation();
     private cachedCatalogCandidates;
-    /** Default slash template 후보 캐시 — chat panel mount 시 1회 빌드 */
     private cachedSlashCandidates;
+    private rebuildMentionCaches;
     /** `@` 마지막 query 의 도메인 사용자 후보 캐시 — userProvider 응답 도착 시 갱신.
      *  query 별 캐시가 아니라 단순 "최근 결과" — async race 회피. */
     private cachedUserCandidates;