@things-factory/ai-assistant 10.1.26 → 10.1.28

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

@@ -1,25 +1,30 @@
 /*
- * A mode is one value, and the point of it is that the parts of a conversation cannot
- * disagree with each other.
+ * A mode is one value, and the point of it is that the parts of a conversation cannot disagree
+ * with each other. Since ADR-0061 decision 7 the parts live on the server: the browser names the
+ * conversation (`kind`) and its subject (`target`), and the persona, the tool categories, the
+ * model and the limits are the app server's.
  *
- * 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.
+ * The defect this still guards against shipped: a screen whose prompt 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. 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 } 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: '이 공간의 지금 상태를 요약해줘' }]
+import { isDifferentConversation, resolveConversation, type AssistantMode, pickInitialMode } from './assistant-mode'
+
+const MODE: AssistantMode = { kind: 'twin.space', target: 'S-12', hostContext: { spaceId: 'S-12' } }
+
+/** What the server said this mode offers, already in the request's locale. */
+const MODE_VIEW = {
+  kind: 'twin.space',
+  slashTemplates: [{ name: 'status', description: 'summarize', template: '이 공간의 지금 상태를 요약해줘' }],
+  catalogEntries: [],
+  proposalChoices: [],
+  footerNotice: undefined,
+  stagedNotice: undefined
 }
 
+/** The board product, which declares no mode and names its own door. */
 const HOST_PROPERTIES = {
-  systemPrompt: 'a prompt the host set the old way',
-  toolCategories: ['board-ai'],
   hostContext: { boardId: 'B-1' },
   chatEndpoint: 'boardAIChat' as const
 }
@@ -27,71 +32,97 @@ const HOST_PROPERTIES = {
 const GLOBAL_DEFAULTS = {
   catalogEntries: [{ type: 'rect' }],
   slashTemplates: [{ name: 'add-monitor', template: '모니터를 추가해줘' }],
-  footerNoticeKey: 'text.previewed-on-the-board'
+  footerNotice: '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'])
+describe('a mode names the conversation; the server says what it offers', () => {
+  test('★ the subject travels, and the door is the neutral one', () => {
+    const c = resolveConversation(MODE, HOST_PROPERTIES, GLOBAL_DEFAULTS, MODE_VIEW)
+
+    expect(c.kind).toBe('twin.space')
+    expect(c.target).toBe('S-12')
     expect(c.hostContext).toEqual({ spaceId: 'S-12' })
+    expect(c.chatEndpoint).toBe('assistantChat')
   })
 
-  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 the mode offers comes from the server, not from what another package registered', () => {
+    const c = resolveConversation(MODE, HOST_PROPERTIES, GLOBAL_DEFAULTS, MODE_VIEW)
 
-  test('★ what a mode leaves out stays out — the defaults another package registered do not fill it', () => {
-    const c = resolveConversation(MODE, HOST_PROPERTIES, GLOBAL_DEFAULTS)
-    /* The board's `@` catalog and its "previewed on the board" line belong to board authoring. */
+    expect(c.slashTemplates).toEqual(MODE_VIEW.slashTemplates)
+    expect(JSON.stringify(c.slashTemplates)).not.toContain('add-monitor')
     expect(c.catalogEntries).toEqual([])
-    expect(c.footerNoticeKey).toBeUndefined()
+    expect(c.footerNotice).toBeUndefined()
   })
 
-  test('★ a mode that declares no slash list offers none, even when a board package registered its own', () => {
-    /* plant's factory mode declares no `slashTemplates`; board-ai registers `/add-monitor` globally. */
-    const { slashTemplates, ...withoutSlash } = MODE
-    const c = resolveConversation({ ...withoutSlash, id: 'plant:factory:D-1' }, HOST_PROPERTIES, GLOBAL_DEFAULTS)
+  test('★ before the server has answered, a mode offers nothing — the defaults do not stand in', () => {
+    const c = resolveConversation(MODE, HOST_PROPERTIES, GLOBAL_DEFAULTS, undefined)
+
     expect(c.slashTemplates).toEqual([])
+    expect(c.catalogEntries).toEqual([])
   })
 
-  test('★ a mode that leaves out a field the host also set as a property does not take the property either', () => {
-    const c = resolveConversation({ id: 'twin:none' }, HOST_PROPERTIES, GLOBAL_DEFAULTS)
-    expect(c.systemPrompt).toBeUndefined()
-    expect(c.toolCategories).toBeUndefined()
-    expect(c.hostContext).toBeUndefined()
+  test('a view for another kind is ignored — the panel is showing this conversation', () => {
+    const c = resolveConversation(MODE, HOST_PROPERTIES, GLOBAL_DEFAULTS, { ...MODE_VIEW, kind: 'twin.board' })
+
+    expect(c.slashTemplates).toEqual([])
   })
+})
 
-  test('a host with no mode gets exactly what it had before modes existed', () => {
+describe('a host with no mode', () => {
+  test('gets its own properties and the registered defaults, as 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.hostContext).toEqual({ boardId: 'B-1' })
     expect(c.slashTemplates).toEqual(GLOBAL_DEFAULTS.slashTemplates)
+    expect(c.footerNotice).toBe('previewed on the board')
+    expect(c.chatEndpoint).toBe('boardAIChat')
   })
 
-  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')
+  test('★ must name its door — there is no default any more', () => {
+    expect(() => resolveConversation(undefined, {}, {})).toThrow(/chatEndpoint/)
   })
 })
 
 describe('isDifferentConversation', () => {
-  const station3: AssistantMode = { id: 'plant:station:3' }
+  const station3: AssistantMode = { kind: 'plant.station', target: '3' }
 
-  test('a different subject ends the conversation', () => {
-    expect(isDifferentConversation(station3, { id: 'plant:station:7' })).toBe(true)
+  test('★ a different subject ends the conversation, and so does a different kind', () => {
+    expect(isDifferentConversation(station3, { kind: 'plant.station', target: '7' })).toBe(true)
+    expect(isDifferentConversation(station3, { kind: 'plant.factory', target: '3' })).toBe(true)
     expect(isDifferentConversation(undefined, station3)).toBe(true)
   })
 
-  test('rewording the same subject does not', () => {
-    expect(isDifferentConversation(station3, { ...station3, systemPrompt: 'reworded' })).toBe(false)
+  test('the same subject, described again, does not', () => {
+    expect(isDifferentConversation(station3, { ...station3, hostContext: { reread: true } })).toBe(false)
     expect(isDifferentConversation(undefined, undefined)).toBe(false)
   })
 })
+
+/*
+ * ADR-0072 A17 ① — 화면을 열 때 어느 대화로 서나.
+ *
+ * 되살리는 것은 고른 대화이지 세션이 아니다. 그리고 없어진 대화로 되살리지 않는다 — 그러면 대화가
+ * 안 열리고 사람은 자기가 무엇을 잘못했는지 알 길이 없다.
+ */
+describe('pickInitialMode', () => {
+  const choices = [
+    { kind: 'twin.board', label: '이 그림 고치기', isDefault: true },
+    { kind: 'twin.space', label: '이 현장 지금', isDefault: false }
+  ]
+
+  it('★ 지난번에 고른 대화로 돌아간다 — 매번 같은 손질을 다시 하지 않는다', () => {
+    expect(pickInitialMode('twin.board', choices, 'twin.space')).toBe('twin.space')
+  })
+
+  it('★ 지금 목록에 없는 기억은 따르지 않는다 — 안 열리는 대화로 들어간다', () => {
+    expect(pickInitialMode('twin.board', choices, 'twin.gone')).toBe('twin.board')
+  })
+
+  it('★ 고를 것이 하나뿐이면 기억을 보지 않는다 — 고른 적이 없는 화면이다', () => {
+    expect(pickInitialMode('plant.station', [choices[0]], 'twin.space')).toBe('plant.station')
+  })
+
+  it('기억이 없으면 host 가 준 것으로 선다', () => {
+    expect(pickInitialMode('twin.board', choices, undefined)).toBe('twin.board')
+  })
+})

package/client/components/assistant-mode.ts

@@ -1,130 +1,172 @@
 /**
- * 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.
+ * A mode is what a conversation *is*: which conversation this is, and what it is about.
  *
- * 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.
+ * Those two used to be nine. The browser declared the persona, the tool categories, the model and
+ * the limits and sent them with every turn, which meant a caller holding the door's privilege
+ * chose its own authority — and it meant a screen could describe a conversation one way while the
+ * server answered it another. Since ADR-0061 decision 7 the app server registers the mode and the
+ * browser names it:
  *
  * ```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>`
+ * html`<ox-assistant-chat .mode=${{ kind: 'twin.space', target: spaceId, hostContext: { spaceId } }}></ox-assistant-chat>`
  * ```
+ *
+ * What the panel shows — the `/` sentences, the `@` catalog, the two notices — comes from the same
+ * declaration, fetched from the server already written in the person's language, so the panel and
+ * the door cannot offer different conversations.
  */
 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`.
+   * Which conversation this is — a `<app>.<surface>` kind the app server registered.
    */
-  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[]
+  kind: string
 
   /**
-   * What `/` offers.
+   * What it is about: the space, the station, the model being edited.
    *
-   * 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.
+   * **With `kind`, this is the conversation's lifetime.** When either changes the chat closes what
+   * is on screen and starts again — a conversation about station 3 is not a conversation about
+   * station 7, and leaving the old one up means the person reads an answer about a screen they are
+   * no longer looking at.
    */
-  slashTemplates?: any[]
-
-  /** The i18n key for the line under an empty conversation. */
-  footerNoticeKey?: string
+  target?: string
 
-  /** Follow-up chips for a proposal that arrived without its own. */
-  proposalChoices?: any[]
+  /**
+   * What the host knows about the subject; travels with each request.
+   *
+   * **The model never sees this** — it reaches the tools as `ctx.host` and nothing else (ADR-0061
+   * decision 7). Anything the model must know is answered by a read tool.
+   */
+  hostContext?: any
+}
 
-  /** The i18n key for the line shown once the host reports a proposal staged. */
-  stagedNoticeKey?: string
+/** What the server said this mode offers, already in the request's locale. */
+export interface AssistantModeView {
+  kind: string
+  slashTemplates: any[]
+  catalogEntries: any[]
+  proposalChoices: any[]
+  placeholder?: string
+  footerNotice?: string
+  stagedNotice?: 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 ?? '')
+  return `${a?.kind ?? ''}|${a?.target ?? ''}` !== `${b?.kind ?? ''}|${b?.target ?? ''}`
 }
 
-/** Everything a conversation needs, after the mode, the host's own properties and the
- *  registered defaults have been reconciled. */
+/** Everything a conversation needs, after the mode, the host's own properties, the registered
+ *  defaults and the server's answer have been reconciled. */
 export interface ConversationSettings {
-  systemPrompt?: string
-  toolCategories?: string[]
+  /** Set when a mode names this conversation; absent for a host that declares none. */
+  kind?: string
+  target?: string
   hostContext?: any
   chatEndpoint: 'boardAIChat' | 'assistantChat'
   catalogEntries: any[]
   slashTemplates: any[]
-  footerNoticeKey?: string
+  /** What the empty input says. A mode's comes translated from the server. */
+  placeholder?: string
+  /** Sentences, not keys — a mode's come translated from the server, a host's from its own i18n. */
+  footerNotice?: string
   proposalChoices: any[]
-  stagedNoticeKey?: string
+  stagedNotice?: string
 }
 
 /**
  * Reconcile the places a setting can come from.
  *
- * **A host that declares a mode gets the mode and nothing else.** A field the mode leaves out is
- * empty: it is not filled from the element's own properties, and it is not filled from the
- * defaults another package registered. Filling it back in is how the defect this type removes
- * returned — board-ai registers board authoring's `/add-monitor`, its component `@` catalog and
- * its "previewed on the board" line globally, and plant's factory mode, which declares no slash
- * list, offered them on a factory screen once the board modeller had been loaded. A mode that
- * wants those declares them.
+ * **A host that declares a mode gets the mode and nothing else.** What the mode does not offer is
+ * not filled in from the element's own properties or from the defaults another package registered.
+ * Filling it back in is how the defect this type removes returned — board-ai registers board
+ * authoring's `/add-monitor`, its component `@` catalog and its "previewed on the board" line
+ * globally, and plant's factory mode, which declares no slash list, offered them on a factory
+ * screen once the board modeller had been loaded.
  *
- * A host that declares no mode gets exactly what it got before modes existed — its own
- * properties, falling back to the registered defaults.
+ * A mode's offering arrives asynchronously, so until the server has answered a mode offers
+ * nothing. Standing the defaults in during that gap would show the board's list for a moment on a
+ * screen that does not edit boards.
  *
- * `chatEndpoint` still falls back to `boardAIChat` when nothing names one; that default is a
- * separate question (standard A2).
+ * A host that declares no mode gets exactly what it got before modes existed — its own properties,
+ * falling back to the registered defaults — and it must name its own door: the `boardAIChat`
+ * default was removed with decision 7, because a missing door should show when a surface is
+ * declared, not when a person says something.
  */
 export function resolveConversation(
   mode: AssistantMode | undefined,
   own: Partial<ConversationSettings>,
-  defaults: Partial<ConversationSettings>
+  defaults: Partial<ConversationSettings>,
+  view?: AssistantModeView
 ): ConversationSettings {
+  if (mode) {
+    /* A view for another kind is the previous conversation's answer arriving late. */
+    const offered = view && view.kind === mode.kind ? view : undefined
+    return {
+      kind: mode.kind,
+      target: mode.target,
+      hostContext: mode.hostContext,
+      chatEndpoint: 'assistantChat',
+      catalogEntries: offered?.catalogEntries ?? [],
+      slashTemplates: offered?.slashTemplates ?? [],
+      proposalChoices: offered?.proposalChoices ?? [],
+      placeholder: offered?.placeholder,
+      footerNotice: offered?.footerNotice,
+      stagedNotice: offered?.stagedNotice
+    }
+  }
+
   const pick = <K extends keyof ConversationSettings>(key: K): ConversationSettings[K] =>
-    mode ? (mode as any)[key] : ((own as any)[key] ?? (defaults as any)[key])
+    (own as any)[key] ?? (defaults as any)[key]
+
+  const chatEndpoint = pick('chatEndpoint')
+  if (!chatEndpoint) {
+    throw new Error(
+      '[ox-assistant-chat] a surface with no mode must name its chatEndpoint. The `boardAIChat` default was ' +
+        'removed (ADR-0061 decision 7) — apps declare a mode and talk to `assistantChat`; the board product ' +
+        'names `boardAIChat` on the element.'
+    )
+  }
 
   return {
-    systemPrompt: pick('systemPrompt'),
-    toolCategories: pick('toolCategories'),
     hostContext: pick('hostContext'),
-    chatEndpoint: pick('chatEndpoint') ?? 'boardAIChat',
+    placeholder: pick('placeholder'),
+    chatEndpoint,
     catalogEntries: pick('catalogEntries') ?? [],
     slashTemplates: pick('slashTemplates') ?? [],
-    footerNoticeKey: pick('footerNoticeKey'),
+    footerNotice: pick('footerNotice'),
     proposalChoices: pick('proposalChoices') ?? [],
-    stagedNoticeKey: pick('stagedNoticeKey')
+    stagedNotice: pick('stagedNotice')
   }
 }
+
+/** 한 subject 위에 설 수 있는 대화 하나 — 서버가 준 목록의 한 줄. */
+export interface AssistantModeChoice {
+  kind: string
+  label: string
+  isDefault: boolean
+}
+
+/**
+ * 이 화면을 열 때 어느 대화로 설 것인가 — ADR-0072 A17 ①.
+ *
+ * ── 왜 기억하나 ───────────────────────────────────────────────────────────
+ * 보드를 열 때마다 저작 대화로 되돌아가면, 현장을 물으려고 온 사람은 화면을 열 때마다 같은 손질을
+ * 다시 한다. 기억은 이 브라우저에만 남는다 — 서버에 칸을 만들지 않는다.
+ *
+ * ── 기억을 언제 버리나 ────────────────────────────────────────────────────
+ * 기억한 종류가 지금 목록에 없으면 따르지 않는다. 대화가 하나 없어진 판으로 바뀌었는데 그 이름으로
+ * 열려고 하면 대화가 안 열리고, 사람은 자기가 무엇을 잘못했는지 알 길이 없다. 그때는 host 가 준
+ * 대화로 둔다.
+ *
+ * 고를 것이 하나뿐이면 기억을 보지 않는다 — 고른 적이 없는 화면이다.
+ */
+export function pickInitialMode(
+  current: string | undefined,
+  choices: ReadonlyArray<AssistantModeChoice>,
+  remembered: string | undefined
+): string | undefined {
+  if (choices.length < 2) return current
+  if (!remembered || remembered === current) return current
+  return choices.some(choice => choice.kind === remembered) ? remembered : current
+}

package/client/components/chat-echo-dedup.test.ts

@@ -228,3 +228,26 @@ describe('AI 답변 에코 흡수 — 영속되지 않는 응답 데이터를
     expect(r.lines[1].id).toBe('a9')
   })
 })
+
+/*
+ * ADR-0073 판정 1 — 가려진 줄이 화면까지 가려진 채로 오는가.
+ *
+ * 서버가 본문을 한 줄로 바꿔 보내도, 클라이언트가 그 사실을 안 들고 오면 말풍선은 그것을 어시스턴트가
+ * 쓴 문장으로 그린다. 그러면 「이 답은 … 권한이 필요합니다」가 어시스턴트의 말이 된다.
+ */
+describe('redacted rows reach the line', () => {
+  it('★ 서버가 가렸다고 하면 줄도 가려진 줄이다', () => {
+    const line = remoteMessageToLine({
+      id: 'm1',
+      role: 'assistant',
+      content: 'this answer needs Query.jobOrders permission',
+      redacted: true
+    } as any)
+
+    expect(line.redacted).toBe(true)
+  })
+
+  it('보통 답은 가려지지 않은 줄이다 — 없는 값을 참으로 읽지 않는다', () => {
+    expect(remoteMessageToLine({ id: 'm2', role: 'assistant', content: '오늘 양품 1,204' } as any).redacted).toBe(false)
+  })
+})

package/client/components/chat-echo-dedup.ts

@@ -31,6 +31,8 @@ export interface RemoteMessage {
   groundingWarningsJson?: any
   /** 발신자 — 표시용 name + **자기 여부 판정용 email**(내부 관리키 id 는 쓰지 않는다). */
   creator?: { name?: string; email?: string } | null
+  /** 이 사람이 이 답의 문을 못 지나 본문이 한 줄로 바뀌어 왔나(ADR-0073 판정 1). */
+  redacted?: boolean
 }
 
 /** 방송 메시지 → 라인. */
@@ -43,7 +45,13 @@ export function remoteMessageToLine(m: RemoteMessage): DedupLine {
     toolUsages: Array.isArray(m.toolUsagesJson) ? m.toolUsagesJson : undefined,
     groundingWarnings: Array.isArray(m.groundingWarningsJson) ? m.groundingWarningsJson : undefined,
     senderEmail: m.creator?.email ?? undefined,
-    senderName: m.creator?.name ?? undefined
+    senderName: m.creator?.name ?? undefined,
+    /*
+     * 서버가 이 사람에게 값을 안 내준 줄 — ADR-0073 판정 1. `content` 에 온 것은 어시스턴트가 쓴
+     * 문장이 아니라 「권한이 필요합니다」 한 줄이다. 그대로 말풍선에 넣으면 어시스턴트가 그렇게 말한
+     * 것처럼 읽힌다.
+     */
+    redacted: m.redacted === true
   }
 }
 
@@ -140,12 +148,30 @@ export function reconcileSentLine(
   patch: Partial<DedupLine>
 ): { lines: DedupLine[]; seen: Set<string> } {
   const idx = lines.findIndex(l => l._localId === localId)
-  if (idx < 0) return { lines, seen }
+  /* 같은 서버 id 를 든 **다른** 줄 — 에코가 흡수되지 못하고 새 줄로 붙은 경우다. */
+  const echoed = serverId ? lines.findIndex((l, i) => i !== idx && l.id === serverId) : -1
+
+  /*
+   * 대기 줄이 없어졌다 — 보내는 동안 대화가 지워졌거나 이력으로 갈렸다. 그래도 **응답이 어느 메시지의
+   * 것인지는 안다**(`assistantMessageId`). 그 줄에 합친다.
+   *
+   * 여기서 그냥 돌아가면, 저장되는 값(본문 · 도구 사용)은 에코가 들고 있으니 화면은 멀쩡해 보이고
+   * **저장되지 않는 것만 사라진다** — 제안 카드다. 모델은 「카드를 눌러 적용하세요」라고 말하고 화면에는
+   * 누를 것이 없다(2026-09-18 트윈에서 실제로 그랬다).
+   */
+  if (idx < 0) {
+    if (echoed < 0) return { lines, seen }
+    const merged = [...lines]
+    merged[echoed] = { ...merged[echoed], ...patch, id: serverId ?? merged[echoed].id }
+    return { lines: merged, seen: serverId ? new Set(seen).add(serverId) : seen }
+  }
 
   const nextLines = [...lines]
   /* seen 만 보고 지우면, 에코를 이 줄에 **흡수**한 경우(id 가 이미 이 줄에 있다) 자기 줄을 지운다.
    * 실제 중복은 "다른 줄이 같은 id 를 가진" 상태일 때뿐이다. */
-  if (serverId && nextLines.some((l, i) => i !== idx && l.id === serverId)) {
+  if (echoed >= 0) {
+    /* 남는 것은 에코 줄이다. 응답에만 있는 것(제안)을 그 줄에 옮기고 대기 줄을 지운다. */
+    nextLines[echoed] = { ...nextLines[echoed], ...patch, id: serverId ?? nextLines[echoed].id }
     nextLines.splice(idx, 1)
     return { lines: nextLines, seen }
   }

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

@@ -14,7 +14,7 @@ import { buildAssistantChatInput, buildChatMutationInput } from './chat-input-bu
 
 const history = [{ role: 'user', content: 'what figures do we have' }]
 
-const args = (over: any = {}) => ({ history, systemPrompt: 'you help someone draw a figure', ...over })
+const args = (over: any = {}) => ({ history, mode: { kind: 'figure.modeller', target: 'fig-1' }, ...over })
 
 describe('the neutral door carries no document', () => {
   it('★ no board field reaches assistantChat', () => {
@@ -25,40 +25,40 @@ describe('the neutral door carries no document', () => {
     }
   })
 
-  it('carries the conversation, the session and the persona', () => {
+  it('carries the conversation, the session and which conversation this is', () => {
     const input = buildAssistantChatInput(args({ sessionId: 's-1' }))
 
     expect(input.sessionId).toBe('s-1')
     expect(input.messages).toBe(history)
-    expect(input.systemPrompt).toBe('you help someone draw a figure')
+    expect(input.mode).toEqual({ kind: 'figure.modeller', target: 'fig-1' })
   })
 
-  it('a one-off question has no session — null, not absent, so the server reads it as ad-hoc', () => {
-    expect(buildAssistantChatInput(args()).sessionId).toBeNull()
+  it('★ the persona, the tools and the limits are not on the wire — they are the server\'s', () => {
+    const input = buildAssistantChatInput(args({ sessionId: 's-1' }))
+
+    for (const field of ['systemPrompt', 'toolCategories', 'model', 'temperature', 'maxTokens', 'requireGroundingTools']) {
+      expect(input).not.toHaveProperty(field)
+    }
   })
-})
 
-describe('the system prompt is required', () => {
-  it('★ refuses an empty prompt instead of sending one', () => {
-    expect(() => buildAssistantChatInput(args({ systemPrompt: '' }))).toThrow(/systemPrompt is required/)
-    expect(() => buildAssistantChatInput(args({ systemPrompt: '   ' }))).toThrow(/systemPrompt is required/)
-    expect(() => buildAssistantChatInput(args({ systemPrompt: undefined }))).toThrow(/systemPrompt is required/)
+  it('a one-off question has no session — null, not absent, so the server reads it as ad-hoc', () => {
+    expect(buildAssistantChatInput(args()).sessionId).toBeNull()
   })
 })
 
-describe('optional fields are sent only when they mean something', () => {
-  it('an unset tool category list is left out — the server default is every registered category', () => {
-    expect(buildAssistantChatInput(args())).not.toHaveProperty('toolCategories')
+describe('the mode is required', () => {
+  it('★ refuses a turn with no mode instead of sending one', () => {
+    expect(() => buildAssistantChatInput(args({ mode: { kind: '' } }))).toThrow(/mode.kind is required/)
+    expect(() => buildAssistantChatInput(args({ mode: { kind: '   ' } }))).toThrow(/mode.kind is required/)
+    expect(() => buildAssistantChatInput(args({ mode: undefined }))).toThrow(/mode.kind is required/)
   })
 
-  it('★ an empty tool category list is sent — it means none, which is a different answer', () => {
-    expect(buildAssistantChatInput(args({ toolCategories: [] })).toolCategories).toEqual([])
+  it('a conversation about nothing in particular carries no target', () => {
+    expect(buildAssistantChatInput(args({ mode: { kind: 'twin.none' } })).mode).toEqual({ kind: 'twin.none' })
   })
+})
 
-  it('grounding is sent only when required — false is the server default', () => {
-    expect(buildAssistantChatInput(args())).not.toHaveProperty('requireGroundingTools')
-    expect(buildAssistantChatInput(args({ requireGroundingTools: true })).requireGroundingTools).toBe(true)
-  })
+describe('optional fields are sent only when they mean something', () => {
 
   it('host context and truncation travel when given', () => {
     const input = buildAssistantChatInput(args({ hostContext: { figureId: 'fig-1' }, truncateAfterMessageId: 'm-9' }))