@things-factory/ai-assistant 10.1.26 → 10.1.28

package/client/components/chat-input-builder.ts

@@ -79,34 +79,36 @@ export function buildChatMutationInput(args: ChatMutationInputArgs): Record<stri
 export interface AssistantChatInputArgs {
   sessionId?: string
   history: Array<{ role: string; content: string }>
-  /** Who the assistant is on this surface. The host owns this prose; the server appends tool rules. */
-  systemPrompt: string
+  /**
+   * Which conversation this is and what it is about. The persona, the tool categories, the model
+   * and the limits belong to the mode the app server registered (ADR-0061 decision 7) — a caller
+   * that could choose its own tool categories was a caller choosing its own authority.
+   */
+  mode: { kind: string; target?: string }
   truncateAfterMessageId?: string
   hostContext?: any
-  toolCategories?: string[]
-  requireGroundingTools?: boolean
 }
 
 /**
  * Build the neutral input.
  *
- * Refuses an empty system prompt instead of sending one. A conversation with no persona still
- * answers — it just answers as nobody, on a surface that never said what it is — and that reads
- * as a bad model rather than a missing argument.
+ * Refuses a conversation with no mode instead of sending one. A turn with no mode has no persona
+ * and no tools, and an answer given as nobody reads like a bad model rather than a missing
+ * argument — the server refuses it too, and this says so where the surface is.
  */
 export function buildAssistantChatInput(args: AssistantChatInputArgs): Record<string, any> {
-  if (!args.systemPrompt?.trim()) {
-    throw new Error('[ox-assistant-chat] systemPrompt is required when the chat talks to assistantChat')
+  if (!args.mode?.kind?.trim()) {
+    throw new Error(
+      '[ox-assistant-chat] mode.kind is required when the chat talks to assistantChat — the app server ' +
+        'registers the mode and the screen names it (ADR-0061 decision 7)'
+    )
   }
 
   return {
     sessionId: args.sessionId ?? null,
     messages: args.history,
-    systemPrompt: args.systemPrompt,
+    mode: { kind: args.mode.kind, ...(args.mode.target ? { target: args.mode.target } : {}) },
     ...(args.truncateAfterMessageId ? { truncateAfterMessageId: args.truncateAfterMessageId } : {}),
-    ...(args.hostContext ? { hostContext: args.hostContext } : {}),
-    /* Absent means every registered category; an empty array means none. Both are meant, so pass it through. */
-    ...(args.toolCategories ? { toolCategories: args.toolCategories } : {}),
-    ...(args.requireGroundingTools ? { requireGroundingTools: true } : {})
+    ...(args.hostContext ? { hostContext: args.hostContext } : {})
   }
 }

package/client/components/chat-proposal-survival.test.ts

@@ -0,0 +1,73 @@
+/*
+ * What this guards: the one thing a turn carries that is never stored — its proposals — survives
+ * the race between the broadcast echo and the mutation's own answer.
+ *
+ * A proposal card exists only in the mutation result. The reply, the tool usages and the grounding
+ * warnings are all in the database, so any path that rebuilds a line from the broadcast looks
+ * right on screen and silently drops the one thing the person can act on. That shipped once
+ * before (the comment in chat-echo-dedup remembers it), and on 2026-09-18 the twin saw it again:
+ * `proposals` came back with one item and the line on screen had no `proposals` field at all.
+ */
+import { receiveRemoteMessage, reconcileSentLine } from './chat-echo-dedup'
+
+const pending = (localId: string) => ({ role: 'assistant', content: '', pending: true, _localId: localId }) as any
+const echo = (id: string) => ({ id, role: 'assistant', content: 'placed at the centre', toolUsagesJson: [{ name: 'proposeSceneEdit' }] }) as any
+const answer = { proposals: [{ tool: 'proposeSceneEdit', proposed: true, kind: 'scene-edit' }], toolUsages: [{ name: 'proposeSceneEdit' }], content: 'placed at the centre', pending: false }
+
+it('★ echo first, then the answer — the card survives', () => {
+  const absorbed = receiveRemoteMessage([pending('local-1-a')], new Set(), echo('server-1'))!
+  const settled = reconcileSentLine(absorbed.lines, absorbed.seen, 'local-1-a', 'server-1', answer as any)
+
+  expect(settled.lines).toHaveLength(1)
+  expect((settled.lines[0] as any).proposals).toHaveLength(1)
+})
+
+it('★ the answer first, then the echo — the card survives', () => {
+  const settled = reconcileSentLine([pending('local-1-a')], new Set(), 'local-1-a', 'server-1', answer as any)
+  const after = receiveRemoteMessage(settled.lines, settled.seen, echo('server-1'))
+
+  /* The echo is already known; it must not append a second line, and it must not replace this one. */
+  const lines = after ? after.lines : settled.lines
+  expect(lines).toHaveLength(1)
+  expect((lines[0] as any).proposals).toHaveLength(1)
+})
+
+it('★ the pending line is gone when the echo arrives — the answer still finds its message', () => {
+  /*
+   * This is the shape the twin saw on 2026-09-18: a line carrying exactly what the database has,
+   * no `proposals` field at all, while the response had one. It happens when the pending line is
+   * no longer in `lines` by the time the echo arrives, and the echo is appended as a new line.
+   *
+   * The answer knows which stored message it is (`assistantMessageId`), so it merges there. What
+   * it must never do is return with the card nowhere: the model tells the person to press a button
+   * that does not exist.
+   */
+  const appended = receiveRemoteMessage([], new Set(), echo('server-1'))!
+  expect((appended.lines[0] as any).proposals).toBeUndefined()
+
+  const settled = reconcileSentLine(appended.lines, appended.seen, 'local-1-a', 'server-1', answer as any)
+
+  expect(settled.lines).toHaveLength(1)
+  expect((settled.lines[0] as any).proposals).toHaveLength(1)
+  expect((settled.lines[0] as any).id).toBe('server-1')
+})
+
+it('★ the echo was appended beside a pending line — the card lands on the message that stays', () => {
+  /*
+   * The duplicate branch used to drop the local line and the answer with it. Everything the
+   * database holds was already on the echo line, so the screen looked complete and only the card
+   * was missing — the exact defect the absorption path exists to prevent.
+   */
+  const withBoth = { lines: [pending('local-1-a'), { id: 'server-1', role: 'assistant', content: 'placed at the centre' }], seen: new Set(['server-1']) }
+
+  const settled = reconcileSentLine(withBoth.lines as any, withBoth.seen, 'local-1-a', 'server-1', answer as any)
+
+  expect(settled.lines).toHaveLength(1)
+  expect((settled.lines[0] as any).proposals).toHaveLength(1)
+})
+
+it('a turn with nothing to merge into is left alone — no line is invented', () => {
+  const settled = reconcileSentLine([], new Set(), 'local-1-a', 'server-9', answer as any)
+
+  expect(settled.lines).toEqual([])
+})

package/client/components/mention-popup.ts

@@ -11,6 +11,7 @@
  * `mention-popup-helpers.ts` 에 분리 — 단위 테스트 가능.
  */
 import { LitElement, css, html } from 'lit'
+import { i18next } from '@operato/i18n'
 import { customElement, property } from 'lit/decorators.js'
 import type { FilterResult, MentionCandidate } from './mention-popup-helpers.js'
 
@@ -32,8 +33,14 @@ export {
   type ResolveMentionTokenOptions
 } from './mention-popup-helpers.js'
 
-/** match type 라벨 — things-scene SearchOverlay 의 MATCH_TYPE_LABELS 와 동일. */
-const MATCH_TYPE_LABEL: Record<string, string> = {
+/**
+ * 어느 칸에서 맞았는지를 말하는 배지, 그리고 후보의 종류 칩.
+ *
+ * 영어 낱말을 그대로 박아 두어서 한국어 화면에 `Name` · `template` 두 낱말만 영어로 서 있었다
+ * [Twin 레인이 화면에서 봄, 2026-09-18]. 화면에 보이는 말이므로 키로 내고 플랫폼이 옮긴다 —
+ * 기본값은 영어다(ADR-0049 ②).
+ */
+const MATCH_TYPE_DEFAULT: Record<string, string> = {
   id: 'ID',
   name: 'Name',
   tag: 'Tag',
@@ -45,6 +52,12 @@ const MATCH_TYPE_LABEL: Record<string, string> = {
   description: 'Desc'
 }
 
+const matchTypeLabel = (matchType: string) =>
+  i18next.t(`ai-assistant.match.${matchType}`, { defaultValue: MATCH_TYPE_DEFAULT[matchType] ?? '' })
+
+/** 후보의 종류 — `template`(슬래시 문장) · `user` · 호스트가 낸 카탈로그 종류. */
+const candidateTypeLabel = (type: string) => i18next.t(`ai-assistant.candidate.${type}`, { defaultValue: type })
+
 @customElement('ox-mention-popup')
 export class OxMentionPopup extends LitElement {
   @property({ type: Array }) results: FilterResult[] = []
@@ -152,7 +165,7 @@ export class OxMentionPopup extends LitElement {
 
   render() {
     if (this.results.length === 0) {
-      return html`<div class="empty">매칭 없음</div>`
+      return html`<div class="empty">${i18next.t('ai-assistant.text.no-match', { defaultValue: 'no match' })}</div>`
     }
     const totalShown = this.results.length
     const totalAll = totalShown + this.overflow
@@ -164,7 +177,7 @@ export class OxMentionPopup extends LitElement {
         // - secondary hint = matchValue 가 label 과 다른 경우 (예: tag/text 매칭) 또는
         //   user 의 email 같은 부가 정보. 없으면 생략.
         const matchType = r.matchType
-        const badgeText = matchType ? MATCH_TYPE_LABEL[matchType] ?? '' : ''
+        const badgeText = matchType ? matchTypeLabel(matchType) : ''
         const label = r.candidate.label
         // matchValue 가 label 과 같으면 redundant 라 hint 안 함
         const matchHint = r.matchValue && r.matchValue !== label ? r.matchValue : ''
@@ -173,7 +186,12 @@ export class OxMentionPopup extends LitElement {
           !matchHint && r.candidate.type === 'user' && r.candidate.email !== label
             ? r.candidate.email ?? ''
             : ''
-        const hint = matchHint || fallbackHint
+        /*
+         * 설명이 있으면 그것을 곁들인다. 슬래시 문장은 이름만으로는 무엇을 하는지 알 수 없다 —
+         * `/bind` 는 「그린 것을 트윈 엔티티에 잇는다」이고, 그 문장이 서버에서 사용자의 언어로
+         * 내려오는데 화면이 그리지 않고 있었다.
+         */
+        const hint = matchHint || fallbackHint || r.candidate.description || ''
         return html`
           <div
             class="item ${i === this.activeIndex ? 'active' : ''}"
@@ -182,16 +200,21 @@ export class OxMentionPopup extends LitElement {
             <span class="match-badge ${badgeText ? '' : 'invisible'}"
               >${badgeText || '·'}</span
             >
-            <span class="type">${r.candidate.type}</span>
+            <span class="type">${candidateTypeLabel(r.candidate.type)}</span>
             <span class="label">${label}</span>
             ${hint ? html`<span class="hint">${hint}</span>` : ''}
           </div>
         `
       })}
       <div class="status">
-        <span>${totalShown} / ${totalAll} matches</span>
+        <span>${i18next.t('ai-assistant.text.match-count', { shown: totalShown, all: totalAll, defaultValue: '{shown} / {all} matches' })}</span>
         ${this.overflow > 0
-          ? html`<span class="more">+${this.overflow} more — narrow query</span>`
+          ? html`<span class="more"
+              >${i18next.t('ai-assistant.text.match-overflow', {
+                count: this.overflow,
+                defaultValue: '+{count} more — narrow the query'
+              })}</span
+            >`
           : ''}
       </div>
     `

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

@@ -0,0 +1,34 @@
+/*
+ * 패널 안에 고르는 축이 둘일 때 — 둘 다 「탭」이라고 말하지 않는다.
+ *
+ * ── 왜 이 시험이 있나 ──────────────────────────────────────────────────────
+ * 대화 고르개를 칩 줄로 만들면서 `role="tablist"` 를 달았다. 바로 아래가 세션 탭이고 그쪽도 tablist
+ * 라서, 화면 낭독기로 들으면 「탭 목록, 대화」 다음에 「탭 목록, Conversation history」 가 이어졌다.
+ * 고르는 축이 둘인데 둘 다 같은 이름으로 불린다. 눈으로 보면 멀쩡해서 화면에서는 안 잡힌다 —
+ * UX 레인이 소스를 읽고 잡았다(2026-09-18).
+ *
+ * 탭 축은 세션 toolbar(`assistant-session-toolbar.ts`)가 갖는다. 이 패널은 자기 탭 축을 세우지 않는다.
+ * ARIA 탭은 좌우 화살표 이동과 `tabpanel` 이 함께 있어야 성립하는데, 여기에는 둘 다 없다.
+ *
+ * 주석은 벗겨 낸다 — 위 문단에 적힌 `role="tablist"` 가 검사를 통과시키면 그 검사는 자기 산문을 센다.
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+function bare(name: string): string {
+  return readFileSync(join(__dirname, name), 'utf-8')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '')
+}
+
+describe('the panel does not raise a second tab axis', () => {
+  it('★ assistant-chat 는 tablist/tab 을 선언하지 않는다 — 그 축은 세션 toolbar의 것이다', () => {
+    const found = [...bare('assistant-chat.ts').matchAll(/role="(tablist|tab)"/g)].map(m => m[1])
+
+    expect(found).toEqual([])
+  })
+
+  it('세션 toolbar는 그 축을 계속 갖는다 — 위 시험이 축을 없애라는 뜻으로 읽히지 않도록', () => {
+    expect(bare('assistant-session-toolbar.ts')).toContain('role="tablist"')
+  })
+})

package/client/components/proposal-outcome-line.ts

@@ -0,0 +1,33 @@
+/*
+ * Reading back what the host did with a proposal (ADR-0070 A12-a).
+ *
+ * The outcome arrives as a `system` row in the conversation — broadcast while the panel is open,
+ * and part of the history after a refresh. The panel reads the card's state from it, so a card
+ * shows what happened rather than what was pressed.
+ *
+ * The shape is the server's (`server/service/chat-message/proposal-outcome.ts`). This parser is
+ * tested against that formatter, so the two cannot drift apart without a test saying so.
+ */
+export interface ParsedProposalOutcome {
+  key: string
+  verdict: 'accepted' | 'refused' | 'unavailable' | 'declined'
+  errorCode?: string
+  applied?: number
+  total?: number
+}
+
+const LINE = /^proposal (.+): (accepted|refused|unavailable|declined)(?: \(([^)]*)\))?(?: (\d+)\/(\d+))?$/
+
+/** Undefined when the row is any other system line — this must not guess. */
+export function parseProposalOutcomeLine(content: string): ParsedProposalOutcome | undefined {
+  const matched = LINE.exec((content ?? '').trim())
+  if (!matched) return undefined
+
+  return {
+    key: matched[1],
+    verdict: matched[2] as ParsedProposalOutcome['verdict'],
+    errorCode: matched[3] || undefined,
+    applied: matched[4] === undefined ? undefined : Number(matched[4]),
+    total: matched[5] === undefined ? undefined : Number(matched[5])
+  }
+}

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

@@ -0,0 +1,75 @@
+/*
+ * What this guards: opening a conversation marks it read, wherever the panel is mounted.
+ *
+ * Read position is a fact other participants see — the unread dot, the bold row in the list. Only
+ * the twin dock called it, by hand, at one of the four places a conversation becomes the open one.
+ * Once a mention can bring someone into a figure or plant conversation, three screens telling
+ * different stories about "read" is the same defect in three places.
+ */
+import { AssistantSessionController } from './assistant-session-controller'
+
+const target = { scope: 'scope-1', anchorType: 'figure', anchorId: 'fig-1' }
+
+function controller(sessions: any[] = [{ id: 's1', name: 'first' }]) {
+  const read: string[] = []
+  const store = new Map<string, string>()
+  const transport = {
+    list: async () => sessions,
+    create: async () => ({ id: 's2', name: 'new' }),
+    isEmpty: async () => false,
+    markRead: async (sessionId: string) => {
+      read.push(sessionId)
+    }
+  }
+  const instance = new AssistantSessionController(
+    transport as any,
+    () => {},
+    { getItem: key => store.get(key) ?? null, setItem: (key, value) => store.set(key, value) }
+  )
+  return { instance, read, transport }
+}
+
+it('★ opening a conversation marks it read', async () => {
+  const { instance, read } = controller()
+
+  await instance.open(target)
+
+  expect(read).toEqual(['s1'])
+})
+
+it('★ switching to another conversation marks that one', async () => {
+  const { instance, read } = controller([{ id: 's1' }, { id: 's9' }])
+  await instance.open(target)
+
+  instance.select('s9')
+
+  expect(read).toEqual(['s1', 's9'])
+})
+
+it('the same conversation staying open is not marked again', async () => {
+  const { instance, read } = controller()
+  await instance.open(target)
+
+  instance.select('s1')
+
+  expect(read).toEqual(['s1'])
+})
+
+it('★ a transport that cannot mark read does not break opening a conversation', async () => {
+  const { instance } = controller()
+  ;(instance as any).transport.markRead = async () => {
+    throw new Error('offline')
+  }
+
+  await expect(instance.open(target)).resolves.toBeUndefined()
+  expect(instance.state.sessionId).toBe('s1')
+})
+
+it('a host with no markRead at all still works — it is optional', async () => {
+  const { instance } = controller()
+  ;(instance as any).transport.markRead = undefined
+
+  await instance.open(target)
+
+  expect(instance.state.sessionId).toBe('s1')
+})

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

@@ -9,6 +9,14 @@ export interface AssistantSessionTransport {
   list(target: AssistantSessionTarget): Promise<AssistantSession[]>
   create(target: AssistantSessionTarget): Promise<AssistantSession>
   isEmpty?(sessionId: string): Promise<boolean>
+  /**
+   * 이 대화를 여기까지 읽었다 — 열린 대화가 바뀔 때 한 번.
+   *
+   * 읽은 지점은 **다른 참여자에게 보이는 사실**이다(안 읽음 배지 · 목록의 굵은 글씨). 도크마다 손으로
+   * 부르던 것을 여기로 올렸다 — twin 만 부르고 있었고, 멘션으로 사람이 들어올 수 있게 된 뒤에는
+   * 세 화면이 같은 사실을 달리 말하게 된다.
+   */
+  markRead?(sessionId: string): Promise<void> | void
 }
 export interface AssistantSessionState {
   target?: AssistantSessionTarget
@@ -53,10 +61,25 @@ export class AssistantSessionController {
   }
 
   private publish(patch: Partial<AssistantSessionState>) {
+    const before = this.state.sessionId
     this.state = { ...this.state, ...patch }
+    /*
+     * 열린 대화가 바뀌면 읽음 지점을 옮긴다. 한 자리에서 하는 이유는 여는 길이 넷이기 때문이다
+     * (열기 · 고르기 · 새로 시작 · 보내며 만들기) — 갈래마다 부르면 한 곳이 빠진다.
+     */
+    if (this.state.sessionId && this.state.sessionId !== before) void this.markRead(this.state.sessionId)
     this.changed(this.state)
   }
 
+  /** 실패는 삼킨다 — 읽음 표시가 못 가는 것이 대화를 막을 이유는 아니다. */
+  private async markRead(sessionId: string): Promise<void> {
+    try {
+      await this.transport.markRead?.(sessionId)
+    } catch {
+      /* noop */
+    }
+  }
+
   async open(target?: AssistantSessionTarget, force = false): Promise<void> {
     const key = keyOf(target)
     if (!force && key === keyOf(this.state.target) && (this.state.loading || this.state.sessionId || (this.lazy && this.state.target && !this.state.error))) return

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

@@ -1,4 +1,5 @@
 import { client } from '@operato/graphql'
+import { i18next } from '@operato/i18n'
 import gql from 'graphql-tag'
 import type { AssistantSessionTransport } from './assistant-session-controller'
 
@@ -10,7 +11,7 @@ export const assistantSessionTransport: AssistantSessionTransport = {
       variables: { id: sessionId }, fetchPolicy: 'no-cache'
     })
     if (result.errors?.length) throw new Error(result.errors[0].message)
-    if (!Array.isArray(result.data?.chatMessages)) throw new Error('대화 내용을 확인하지 못했습니다.')
+    if (!Array.isArray(result.data?.chatMessages)) throw new Error(i18next.t('ai-assistant.text.messages-unreadable', { defaultValue: 'could not read this conversation.' }))
     return result.data.chatMessages.length === 0
   },
   async list(target) {
@@ -19,16 +20,23 @@ export const assistantSessionTransport: AssistantSessionTransport = {
       variables: { type: target.anchorType, id: target.anchorId }, fetchPolicy: 'no-cache'
     })
     if (result.errors?.length) throw new Error(result.errors[0].message)
-    if (!Array.isArray(result.data?.chatSessionInbox)) throw new Error('대화 목록을 불러오지 못했습니다.')
+    if (!Array.isArray(result.data?.chatSessionInbox)) throw new Error(i18next.t('ai-assistant.text.sessions-unreadable', { defaultValue: 'could not load the conversation list.' }))
     return result.data.chatSessionInbox
   },
+  async markRead(sessionId) {
+    /* 참여자가 아닌 대화(내 읽음 지점이 없는 자리)면 서버가 false 를 돌려준다 — 그것도 답이다. */
+    await client.mutate({
+      mutation: gql`mutation($id:String!){markSessionRead(sessionId:$id)}`,
+      variables: { id: sessionId }
+    })
+  },
   async create(target) {
     const result = await client.mutate({
       mutation: gql`mutation($type:String!,$id:String!){createAISession(anchorType:$type,anchorId:$id){id name}}`,
       variables: { type: target.anchorType, id: target.anchorId }
     })
     if (result.errors?.length) throw new Error(result.errors[0].message)
-    if (!result.data?.createAISession?.id) throw new Error('대화를 만들지 못했습니다.')
+    if (!result.data?.createAISession?.id) throw new Error(i18next.t('ai-assistant.text.session-not-created', { defaultValue: 'could not start a conversation.' }))
     return result.data.createAISession
   }
 }