@things-factory/ai-assistant 10.1.28 → 10.1.31

package/client/components/assistant-chat.ts

@@ -219,6 +219,8 @@ const ASSISTANT_MODE_QUERY = gql`
       catalogEntries
       proposalChoices
       placeholder
+      intro
+      examples
       footerNotice
       stagedNotice
     }
@@ -563,6 +565,22 @@ export class OxAssistantChat extends LitElement {
   @state()
   private dragOver = false
 
+  /*
+   * ── 왜 이미지만 받나 ──────────────────────────────────────────────────────
+   * `.json` · `.txt` · `.csv` 도 받고 있었다. 그 파일들은 `hostContext.attachments` 로 실려 갔고
+   * **그것을 읽어 모델에 붙이는 코드가 없었다.** 사람이 CSV 를 붙이고 「이 표 좀 봐줘」라고 하면 화면에
+   * 파일 칩이 뜨고 답도 왔다. 그 답은 파일을 본 적이 없고, 오류도 안 났다(2026-09-18 표면 조사).
+   *
+   * 이미지는 길이 있다 — `assistant-chat-resolver.ts` 가 `hostContext.image` 를 마지막 사람 턴에
+   * 붙인다. 그래서 되는 것만 남기고 좁혔다. 못 하는 일을 화면이 권하지 않는다.
+   *
+   * ── 글 파일을 청하는 제품이 설 때의 모양 (수석 아키텍트, ADR-0071 보탬) ───
+   * 이미지와 **같은 자리**(사람 턴)에 붙인다. 크기 상한은 모드가 선언하고, 넘으면 보내기 전에 사실 한
+   * 줄로 거절한다 — 조용히 자르지 않는다. 비용은 사용량의 축이다(ADR-0061 결정 6).
+   *
+   * `attachments` 짐 자체는 그대로 둔다: figure 의 도구가 거기서 이미지를 찾는다
+   * (`figure-tools.ts` — `ctx.host.image` 가 없을 때의 갈래).
+   */
   private async onAttachFiles(files: FileList | File[] | null | undefined) {
     if (!files || files.length === 0) return
     const list = Array.from(files)
@@ -875,13 +893,29 @@ export class OxAssistantChat extends LitElement {
    */
   private onModePick(kind: string) {
     if (!this.mode || kind === this.mode.kind) return
-    this.mode = { ...this.mode, kind }
     try {
       if (this.subject) localStorage.setItem(`assistant-mode:${this.subject}`, kind)
     } catch {
       /* 저장이 막힌 브라우저에서도 고르기 자체는 된다 — 다음에 다시 고르면 될 뿐이다. */
     }
-    this.dispatchEvent(new CustomEvent('assistant-mode-change', { detail: { kind, subject: this.subject }, bubbles: true, composed: true }))
+    this.askHostForMode(kind)
+  }
+
+  /**
+   * **고르는 것은 청하는 일이다** — `mode` 를 여기서 바꾸지 않는다.
+   *
+   * host 는 렌더마다 `mode` 를 다시 내려 준다. 패널이 자기 손으로 고쳐 두면 다음 렌더가 그것을 덮고,
+   * 더 나쁜 것은 host 가 **자기가 무엇을 열었는지 모르는 채로 남는다**는 것이다. host 는 대화의 세션을
+   * 대상별로 들고 있으므로, 대화가 바뀐 것을 모르면 앞 대화의 세션을 그대로 넘긴다 — 그러면 새 말이 앞
+   * 대화에 붙는다(2026-09-18 Figure 레인이 :3300 에서 본 것이 이것이다).
+   *
+   * 그래서 주인은 하나다: host 가 `mode` 를 갖고, 패널은 「이것으로 바꿔 달라」고 말한다. 기억은 패널이
+   * 진다(브라우저마다 다른 값이라 host 가 질 것이 아니다) — 기억한 것을 되살릴 때도 같은 청으로 나간다.
+   */
+  private askHostForMode(kind: string) {
+    this.dispatchEvent(
+      new CustomEvent('assistant-mode-change', { detail: { kind, subject: this.subject }, bubbles: true, composed: true })
+    )
   }
 
   /** 이 subject 에서 지난번에 고른 대화 — 없으면 undefined. */
@@ -2541,7 +2575,7 @@ export class OxAssistantChat extends LitElement {
     if (this.modeChoices.length < 2 || !this.subject || !this.mode) return
 
     const kind = pickInitialMode(this.mode.kind, this.modeChoices, this.rememberedMode(this.subject))
-    if (kind && kind !== this.mode.kind) this.mode = { ...this.mode, kind }
+    if (kind && kind !== this.mode.kind) this.askHostForMode(kind)
   }
 
   updated(changed: Map<string, any>) {
@@ -2905,7 +2939,7 @@ export class OxAssistantChat extends LitElement {
             id="chat-file-input"
             type="file"
             multiple
-            accept="image/*,.json,.txt,.csv"
+            accept="image/*"
             style="display: none"
             @change=${(e: Event) => {
               const input = e.target as HTMLInputElement
@@ -2919,7 +2953,7 @@ export class OxAssistantChat extends LitElement {
             type="button"
             class="action"
             @click=${() => this.renderRoot.querySelector<HTMLInputElement>('#chat-file-input')?.click()}
-            title=${i18next.t('ai-assistant.tooltip.attach-file', { defaultValue: 'Attach images or files (drag & drop or paste supported)' })}>
+            title=${i18next.t('ai-assistant.tooltip.attach-file', { defaultValue: 'attach an image (drag & drop or paste supported)' })}>
             <md-icon>attach_file</md-icon>
             ${i18next.t('ai-assistant.button.attach', { defaultValue: 'Attach' })}
           </button>
@@ -3444,6 +3478,11 @@ export class OxAssistantChat extends LitElement {
    * 읽었고, 그러면 호스트 값을 한쪽만 반영하는 상태가 만들어질 수 있었다.
    */
   private get exampleGroups(): Array<{ label: string; items: string[] }> {
+    /*
+     * 대화가 자기 예시를 가지면 그것이 먼저다 — 자리표·`/` 와 같은 차례(ADR-0061 결정 7). host 속성은
+     * 대화를 모르므로, 한 화면에 대화가 둘 서면 한쪽에 맞는 글이 다른 쪽에도 뜬다.
+     */
+    if (this.modeView?.examples?.length) return this.modeView.examples
     if (this.examples?.length) return this.examples
     return OxAssistantChat.EXAMPLE_GROUPS.map(group => ({
       label: i18next.t(group.labelKey),
@@ -3605,8 +3644,13 @@ export class OxAssistantChat extends LitElement {
       <div class="empty">
         <div class="header">
           <md-icon class="icon">auto_awesome</md-icon>
-          <div class="title">${this.intro?.title ?? i18next.t('ai-assistant.text.empty-title')}</div>
-          <div class="subtitle">${this.intro?.subtitle ?? i18next.t('ai-assistant.text.empty-subtitle')}</div>
+          <!-- 대화가 자기 글을 가지면 그것이 먼저다 — host 속성은 대화를 모른다. -->
+          <div class="title">
+            ${this.modeView?.intro?.title ?? this.intro?.title ?? i18next.t('ai-assistant.text.empty-title')}
+          </div>
+          <div class="subtitle">
+            ${this.modeView?.intro?.subtitle ?? this.intro?.subtitle ?? i18next.t('ai-assistant.text.empty-subtitle')}
+          </div>
         </div>
 
         ${this.triggerChips.length > 0

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

@@ -9,7 +9,7 @@
  * the slash list was a module global. A mode's wording now comes from the same declaration the
  * door reads, so the two cannot describe different conversations.
  */
-import { isDifferentConversation, resolveConversation, type AssistantMode, pickInitialMode } from './assistant-mode'
+import { isDifferentConversation, resolveConversation, type AssistantMode, pickInitialMode, followPickedConversation } from './assistant-mode'
 
 const MODE: AssistantMode = { kind: 'twin.space', target: 'S-12', hostContext: { spaceId: 'S-12' } }
 
@@ -126,3 +126,22 @@ describe('pickInitialMode', () => {
     expect(pickInitialMode('twin.board', choices, undefined)).toBe('twin.board')
   })
 })
+
+/*
+ * ADR-0072 결정 3 — 목록에서 고른 대화로 화면이 따라간다.
+ */
+describe('followPickedConversation', () => {
+  it('★ 다른 대화의 세션을 고르면 그 대화로 간다 — 안 따라가면 문이 거절한다', () => {
+    expect(followPickedConversation('figure.catalog', 'figure.modeller')).toBe('figure.catalog')
+  })
+
+  it('같은 대화면 그대로 둔다', () => {
+    expect(followPickedConversation('figure.modeller', 'figure.modeller')).toBeUndefined()
+  })
+
+  it('★ 칸이 서기 전 세션은 지금 대화로 둔다 — 서버가 다음 턴에 찍는다', () => {
+    expect(followPickedConversation(undefined, 'figure.modeller')).toBeUndefined()
+    expect(followPickedConversation(null, 'figure.modeller')).toBeUndefined()
+    expect(followPickedConversation('', 'figure.modeller')).toBeUndefined()
+  })
+})

package/client/components/assistant-mode.ts

@@ -47,6 +47,10 @@ export interface AssistantModeView {
   catalogEntries: any[]
   proposalChoices: any[]
   placeholder?: string
+  /** 빈 대화의 제목과 한 줄 — 이 대화가 무엇을 하는 자리인지. host 속성보다 앞선다. */
+  intro?: { title: string; subtitle: string }
+  /** 빈 대화의 예시 — 이 대화에서 실제로 할 수 있는 말. host 속성보다 앞선다. */
+  examples?: Array<{ label: string; items: string[] }>
   footerNotice?: string
   stagedNotice?: string
 }
@@ -170,3 +174,19 @@ export function pickInitialMode(
   if (!remembered || remembered === current) return current
   return choices.some(choice => choice.kind === remembered) ? remembered : current
 }
+
+/**
+ * 목록에서 고른 대화로 따라갈 것인가 — ADR-0072 결정 3.
+ *
+ * 목록은 한 대상의 대화를 **모두** 보여 주고, 그 대상 위에는 대화가 둘 설 수 있다(A17). 고른 것이 지금
+ * 열린 대화와 다른데 화면이 그대로 있으면 문이 거절하고(`session-kind-mismatch`), 목록은 눌리는데 안
+ * 열리는 목록이 된다 — 선언은 있고 길이 없는 그 모양이다.
+ *
+ * 칸이 서기 전에 난 세션에는 값이 없다. 그때는 지금 대화로 둔다 — 서버가 다음 턴에 지금 대화로 찍는다.
+ *
+ * `undefined` 는 「그대로 둔다」는 뜻이다.
+ */
+export function followPickedConversation(pickedKind: string | undefined | null, currentKind: string | undefined): string | undefined {
+  if (!pickedKind || pickedKind === currentKind) return undefined
+  return pickedKind
+}

package/client/components/panel-aria.test.ts

@@ -32,3 +32,23 @@ describe('the panel does not raise a second tab axis', () => {
     expect(bare('assistant-session-toolbar.ts')).toContain('role="tablist"')
   })
 })
+
+/*
+ * 첨부는 **되는 것만** 권한다 — ADR-0071 보탬(2026-09-18).
+ *
+ * `.json` · `.txt` · `.csv` 도 받고 있었는데, 그 파일들은 실려만 가고 모델에 붙는 코드가 없었다. 사람이
+ * CSV 를 붙이고 물으면 파일 칩이 뜨고 답도 왔다 — 그 답은 파일을 본 적이 없고 오류도 안 났다.
+ * 이미지는 `hostContext.image` 로 사람 턴에 붙는 길이 있다.
+ */
+describe('the attach control offers only what has a path', () => {
+  it('★ 이미지만 받는다 — 읽히지 않는 것을 화면이 권하지 않는다', () => {
+    /*
+     * 여기서는 주석을 안 벗긴다. `image/*` 자체가 `/*` 를 품고 있어서, 주석 벗기개가 그 자리를 주석의
+     * 시작으로 읽고 다음 `*` + `/` 까지 지워 버린다 — 값이 사라지고 시험은 「없다」고 답한다.
+     * 이 값은 주석에 적힐 일이 없으므로 원문에서 그대로 읽는다.
+     */
+    const accept = readFileSync(join(__dirname, 'assistant-chat.ts'), 'utf-8').match(/accept="([^"]*)"/)
+
+    expect(accept?.[1]).toBe('image/*')
+  })
+})

package/client/utils/assistant-session-controller.ts

@@ -1,4 +1,17 @@
-export interface AssistantSession { id: string; name?: string }
+export interface AssistantSession {
+  id: string
+  name?: string
+  /**
+   * 어느 대화인가 — 등록된 모드의 kind (ADR-0072 결정 3).
+   *
+   * 목록은 한 대상의 대화를 **모두** 보여 준다. 그 대상 위에 대화가 둘 설 수 있으므로(A17), 고른 것이
+   * 지금 열려 있는 대화와 다를 수 있다. 그때 화면은 그 대화로 따라가야 한다 — 안 그러면 문이 거절하고
+   * (`session-kind-mismatch`), 목록은 눌리는데 안 열리는 목록이 된다.
+   *
+   * 칸이 서기 전에 난 세션에는 값이 없다. 그때는 지금 대화로 두고, 서버가 다음 턴에 찍는다.
+   */
+  kind?: string
+}
 export interface AssistantSessionTarget {
   /** Account/domain boundary supplied by the authenticated host. */
   scope: string

package/client/utils/assistant-session-transport.ts

@@ -16,7 +16,7 @@ export const assistantSessionTransport: AssistantSessionTransport = {
   },
   async list(target) {
     const result = await client.query({
-      query: gql`query($type:String!,$id:String!){chatSessionInbox(anchorType:$type,anchorId:$id,mineOnly:true,limit:100){id name}}`,
+      query: gql`query($type:String!,$id:String!){chatSessionInbox(anchorType:$type,anchorId:$id,mineOnly:true,limit:100){id name kind}}`,
       variables: { type: target.anchorType, id: target.anchorId }, fetchPolicy: 'no-cache'
     })
     if (result.errors?.length) throw new Error(result.errors[0].message)
@@ -32,7 +32,7 @@ export const assistantSessionTransport: AssistantSessionTransport = {
   },
   async create(target) {
     const result = await client.mutate({
-      mutation: gql`mutation($type:String!,$id:String!){createAISession(anchorType:$type,anchorId:$id){id name}}`,
+      mutation: gql`mutation($type:String!,$id:String!){createAISession(anchorType:$type,anchorId:$id){id name kind}}`,
       variables: { type: target.anchorType, id: target.anchorId }
     })
     if (result.errors?.length) throw new Error(result.errors[0].message)

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

@@ -326,6 +326,18 @@ export declare class OxAssistantChat extends LitElement {
      * (서버에 칸을 만들지 않는다 — A17 ①). 세션 자체는 자기가 어느 대화였는지 이미 안다.
      */
     private onModePick;
+    /**
+     * **고르는 것은 청하는 일이다** — `mode` 를 여기서 바꾸지 않는다.
+     *
+     * host 는 렌더마다 `mode` 를 다시 내려 준다. 패널이 자기 손으로 고쳐 두면 다음 렌더가 그것을 덮고,
+     * 더 나쁜 것은 host 가 **자기가 무엇을 열었는지 모르는 채로 남는다**는 것이다. host 는 대화의 세션을
+     * 대상별로 들고 있으므로, 대화가 바뀐 것을 모르면 앞 대화의 세션을 그대로 넘긴다 — 그러면 새 말이 앞
+     * 대화에 붙는다(2026-09-18 Figure 레인이 :3300 에서 본 것이 이것이다).
+     *
+     * 그래서 주인은 하나다: host 가 `mode` 를 갖고, 패널은 「이것으로 바꿔 달라」고 말한다. 기억은 패널이
+     * 진다(브라우저마다 다른 값이라 host 가 질 것이 아니다) — 기억한 것을 되살릴 때도 같은 청으로 나간다.
+     */
+    private askHostForMode;
     /** 이 subject 에서 지난번에 고른 대화 — 없으면 undefined. */
     private rememberedMode;
     private loadModeView;

package/dist-client/components/assistant-chat.js

@@ -129,6 +129,8 @@ const ASSISTANT_MODE_QUERY = gql `
       catalogEntries
       proposalChoices
       placeholder
+      intro
+      examples
       footerNotice
       stagedNotice
     }
@@ -387,6 +389,22 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
         this.proposalSentAt = new Map();
     }
     static { OxAssistantChat_1 = this; }
+    /*
+     * ── 왜 이미지만 받나 ──────────────────────────────────────────────────────
+     * `.json` · `.txt` · `.csv` 도 받고 있었다. 그 파일들은 `hostContext.attachments` 로 실려 갔고
+     * **그것을 읽어 모델에 붙이는 코드가 없었다.** 사람이 CSV 를 붙이고 「이 표 좀 봐줘」라고 하면 화면에
+     * 파일 칩이 뜨고 답도 왔다. 그 답은 파일을 본 적이 없고, 오류도 안 났다(2026-09-18 표면 조사).
+     *
+     * 이미지는 길이 있다 — `assistant-chat-resolver.ts` 가 `hostContext.image` 를 마지막 사람 턴에
+     * 붙인다. 그래서 되는 것만 남기고 좁혔다. 못 하는 일을 화면이 권하지 않는다.
+     *
+     * ── 글 파일을 청하는 제품이 설 때의 모양 (수석 아키텍트, ADR-0071 보탬) ───
+     * 이미지와 **같은 자리**(사람 턴)에 붙인다. 크기 상한은 모드가 선언하고, 넘으면 보내기 전에 사실 한
+     * 줄로 거절한다 — 조용히 자르지 않는다. 비용은 사용량의 축이다(ADR-0061 결정 6).
+     *
+     * `attachments` 짐 자체는 그대로 둔다: figure 의 도구가 거기서 이미지를 찾는다
+     * (`figure-tools.ts` — `ctx.host.image` 가 없을 때의 갈래).
+     */
     async onAttachFiles(files) {
         if (!files || files.length === 0)
             return;
@@ -567,7 +585,6 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
     onModePick(kind) {
         if (!this.mode || kind === this.mode.kind)
             return;
-        this.mode = { ...this.mode, kind };
         try {
             if (this.subject)
                 localStorage.setItem(`assistant-mode:${this.subject}`, kind);
@@ -575,6 +592,20 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
         catch {
             /* 저장이 막힌 브라우저에서도 고르기 자체는 된다 — 다음에 다시 고르면 될 뿐이다. */
         }
+        this.askHostForMode(kind);
+    }
+    /**
+     * **고르는 것은 청하는 일이다** — `mode` 를 여기서 바꾸지 않는다.
+     *
+     * host 는 렌더마다 `mode` 를 다시 내려 준다. 패널이 자기 손으로 고쳐 두면 다음 렌더가 그것을 덮고,
+     * 더 나쁜 것은 host 가 **자기가 무엇을 열었는지 모르는 채로 남는다**는 것이다. host 는 대화의 세션을
+     * 대상별로 들고 있으므로, 대화가 바뀐 것을 모르면 앞 대화의 세션을 그대로 넘긴다 — 그러면 새 말이 앞
+     * 대화에 붙는다(2026-09-18 Figure 레인이 :3300 에서 본 것이 이것이다).
+     *
+     * 그래서 주인은 하나다: host 가 `mode` 를 갖고, 패널은 「이것으로 바꿔 달라」고 말한다. 기억은 패널이
+     * 진다(브라우저마다 다른 값이라 host 가 질 것이 아니다) — 기억한 것을 되살릴 때도 같은 청으로 나간다.
+     */
+    askHostForMode(kind) {
         this.dispatchEvent(new CustomEvent('assistant-mode-change', { detail: { kind, subject: this.subject }, bubbles: true, composed: true }));
     }
     /** 이 subject 에서 지난번에 고른 대화 — 없으면 undefined. */
@@ -2219,7 +2250,7 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
             return;
         const kind = pickInitialMode(this.mode.kind, this.modeChoices, this.rememberedMode(this.subject));
         if (kind && kind !== this.mode.kind)
-            this.mode = { ...this.mode, kind };
+            this.askHostForMode(kind);
     }
     updated(changed) {
         /*
@@ -2578,7 +2609,7 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
             id="chat-file-input"
             type="file"
             multiple
-            accept="image/*,.json,.txt,.csv"
+            accept="image/*"
             style="display: none"
             @change=${(e) => {
             const input = e.target;
@@ -2592,7 +2623,7 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
             type="button"
             class="action"
             @click=${() => this.renderRoot.querySelector('#chat-file-input')?.click()}
-            title=${i18next.t('ai-assistant.tooltip.attach-file', { defaultValue: 'Attach images or files (drag & drop or paste supported)' })}>
+            title=${i18next.t('ai-assistant.tooltip.attach-file', { defaultValue: 'attach an image (drag & drop or paste supported)' })}>
             <md-icon>attach_file</md-icon>
             ${i18next.t('ai-assistant.button.attach', { defaultValue: 'Attach' })}
           </button>
@@ -3061,6 +3092,12 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
      * 읽었고, 그러면 호스트 값을 한쪽만 반영하는 상태가 만들어질 수 있었다.
      */
     get exampleGroups() {
+        /*
+         * 대화가 자기 예시를 가지면 그것이 먼저다 — 자리표·`/` 와 같은 차례(ADR-0061 결정 7). host 속성은
+         * 대화를 모르므로, 한 화면에 대화가 둘 서면 한쪽에 맞는 글이 다른 쪽에도 뜬다.
+         */
+        if (this.modeView?.examples?.length)
+            return this.modeView.examples;
         if (this.examples?.length)
             return this.examples;
         return OxAssistantChat_1.EXAMPLE_GROUPS.map(group => ({
@@ -3201,8 +3238,13 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
       <div class="empty">
         <div class="header">
           <md-icon class="icon">auto_awesome</md-icon>
-          <div class="title">${this.intro?.title ?? i18next.t('ai-assistant.text.empty-title')}</div>
-          <div class="subtitle">${this.intro?.subtitle ?? i18next.t('ai-assistant.text.empty-subtitle')}</div>
+          <!-- 대화가 자기 글을 가지면 그것이 먼저다 — host 속성은 대화를 모른다. -->
+          <div class="title">
+            ${this.modeView?.intro?.title ?? this.intro?.title ?? i18next.t('ai-assistant.text.empty-title')}
+          </div>
+          <div class="subtitle">
+            ${this.modeView?.intro?.subtitle ?? this.intro?.subtitle ?? i18next.t('ai-assistant.text.empty-subtitle')}
+          </div>
         </div>
 
         ${this.triggerChips.length > 0