@things-factory/board-ai 10.1.159 → 10.1.161

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/board-ai",
-  "version": "10.1.159",
+  "version": "10.1.161",
   "main": "dist-server/index.js",
   "browser": "dist-client/client/index.js",
   "things-factory": true,
@@ -32,7 +32,7 @@
     "@operato/i18n": "^10.0.0",
     "@operato/scene-ops": "^10.14.1",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-assistant": "^10.1.159",
+    "@things-factory/ai-assistant": "^10.1.161",
     "@things-factory/ai-client-base": "^10.1.159",
     "@things-factory/auth-base": "^10.1.159",
     "@things-factory/board-import": "^10.1.159",
@@ -47,5 +47,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "fc15cdcb18e562ca1e723a1e1bf042f9582cbbfb"
+  "gitHead": "d32fe0614ea40572787acd94e307cc18a681ab38"
 }

package/server/service/assistant.test.ts

@@ -834,7 +834,7 @@ describe('Tool 분류 (read/write)', () => {
 })
 
 describe('buildBoardEditTools — refid 기반 tool 이름 (식별자 정책 회귀 방지)', () => {
-  test('41개 tool 모두 정의 (25 write + 8 read + 4 ephemeral action + 4 import)', () => {
+  test('42개 tool 모두 정의 (25 write + 9 read + 4 ephemeral action + 4 import)', () => {
     const tools = buildBoardEditTools(['rect', 'circle'])
     const names = tools.map(t => t.name).sort()
     expect(names).toEqual([
@@ -853,6 +853,7 @@ describe('buildBoardEditTools — refid 기반 tool 이름 (식별자 정책 회
       'fitToView',
       'getAtmosphereGuide',
       'getAvailablePrefabs',
+      'getBoardOutline',
       'getColorPalettes',
       'getComponentByRefid',
       'getComponentStyle',
@@ -1617,8 +1618,8 @@ describe('agentic loop (chatViaTools) — mock provider', () => {
         id: 'mock:test',
         chat: async () => '',
         generateJSON: async () => ({}),
-        chatWithTools: async (messages: any[], _tools: any[], _options: any) => {
-          callLog.push({ messages: JSON.parse(JSON.stringify(messages)) })
+        chatWithTools: async (messages: any[], _tools: any[], options: any) => {
+          callLog.push({ messages: JSON.parse(JSON.stringify(messages)), systemPrompt: options?.systemPrompt ?? '' })
           const turn = turns[turnIdx++] ?? { toolCalls: [], stopReason: 'end_turn' }
           return {
             text: turn.text,
@@ -1736,23 +1737,36 @@ describe('agentic loop (chatViaTools) — mock provider', () => {
     expect(r).toBeDefined()
   })
 
-  test('selectedRefids 비어 있어도 selection 컨텍스트는 항상 포함', async () => {
+  /*
+   * The board and the selection are not pasted into the request (operato-application design/ai/screen-pattern.md
+   * §2-2, ruled 2026-10-13): the open board is named by the server's line, its contents are read with tools.
+   */
+  test('★ the request carries the person\'s words only - no board JSON, no selection list', async () => {
     const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
     const a = new DefaultBoardAIAssistant(client)
-    await a.chat([{ role: 'user', content: 'q' }], undefined)
-    const firstUser = callLog[0].messages[0]
-    expect(firstUser.role).toBe('user')
-    expect(firstUser.content).toMatch(/No component is currently selected/i)
+    const board: any = { width: 800, components: [{ type: 'rect', refid: 7, left: 10 }] }
+    await a.chat([{ role: 'user', content: 'q' }], board, { selectedRefids: [7] })
+    expect(callLog[0].messages).toEqual([{ role: 'user', content: 'q' }])
+    expect(JSON.stringify(callLog[0])).not.toMatch(/Current board state|User-selected component refids/)
   })
 
-  test('selectedRefids 가 있을 때 selection 컨텍스트가 refid 명시', async () => {
+  test('★ the system prompt names the open board through the server\'s line, and says to read the board and the selection', async () => {
     const { client, callLog } = makeMockClient([{ text: 'ok', toolCalls: [] }])
     const a = new DefaultBoardAIAssistant(client)
-    await a.chat([{ role: 'user', content: 'q' }], undefined, { selectedRefids: [35, 37] })
-    const firstUser = callLog[0].messages[0]
-    expect(firstUser.content).toMatch(/User-selected component refids/i)
-    expect(firstUser.content).toContain('[35,37]')
-    expect(firstUser.content).toMatch(/getSelection/i)
+    const line = 'On this screen the person has the board named "Line 1" open (id b1).'
+    await a.chat([{ role: 'user', content: 'q' }], undefined, { openSubject: line })
+    expect(callLog[0].systemPrompt).toContain(`==== OPEN SUBJECT ====\n${line}`)
+    expect(callLog[0].systemPrompt).toMatch(/Read the board with `getBoardOutline`/)
+    expect(callLog[0].systemPrompt).toMatch(/the selection with `getSelection`/)
+  })
+
+  test('★ getBoardOutline is the summary the request used to carry', () => {
+    const board: any = { width: 800, components: [{ type: 'rect', refid: 7, left: 10 }] }
+    expect(executeReadTool({ id: '1', name: 'getBoardOutline', arguments: {} } as any, board, [])).toEqual(summarizeBoard(board))
+    expect(executeReadTool({ id: '1', name: 'getBoardOutline', arguments: {} } as any, undefined, [])).toEqual({
+      empty: true,
+      message: 'No board is open in this conversation.'
+    })
   })
 
   test('system prompt 가 id vs refid 정책을 AI 한테 명시', async () => {

package/server/service/assistant.ts

@@ -192,38 +192,28 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
      * 모아 붙이기만 한다(도메인 지식이 board-ai 프롬프트로 새지 않는다). */
     const guidance = getCategoryGuidance(options.toolCategories)
     const surface = (options.surfacePrompt ?? '').trim()
+    const openSubject = (options.openSubject ?? '').trim()
     const systemPrompt =
       this.buildSystemPromptForTools(knownTypes, categories, schemas) +
       (surface ? `\n\n==== THIS SURFACE (declared by the app) ====\n${surface}` : '') +
+      /* Which board is open - the server's line from the stored anchor, the one way the model learns it (screen-pattern §2-1). */
+      (openSubject ? `\n\n==== OPEN SUBJECT ====\n${openSubject}` : '') +
+      (gate.coreOn ? `\n\n${READ_THE_BOARD}` : '') +
       (guidance.length ? `\n\n==== TOOL USE RULES (from the tools exposed to this conversation) ====\n${guidance.join('\n')}` : '') +
       (!gate.coreOn && options.boardToolsWithheld ? `\n\n${BOARD_EDIT_WITHHELD}` : '')
 
     const selectedRefids = (options.selectedRefids ?? []).filter(
       (n): n is number => typeof n === 'number' && Number.isFinite(n)
     )
-    // selection 정보는 항상 포함 (비어 있어도) — LLM 이 "선택된 게 뭐냐" 류 질문에
-    // getSelection 을 호출할지 판단하는 데 필요.
-    const selectionContext = selectedRefids.length > 0
-      ? `\n\nUser-selected component refids: ${JSON.stringify(selectedRefids)}\n` +
-        `When the user says "selected" / "선택한" / "this" / "그것" / "these" etc. ` +
-        `WITHOUT specifying targets, operate ONLY on these refids. ` +
-        `Do not modify other components unless explicitly asked. ` +
-        `For inspecting selected components, prefer calling \`getSelection\` over guessing.`
-      : `\n\nNo component is currently selected. If the user asks about "selected" / "this", ` +
-        `clarify or call \`getSelection\` to confirm.`
-
-    const boardContext = currentBoard
-      ? `Current board state (JSON, summarized; full details via \`getComponent\` / \`findComponents\`):\n` +
-        `${JSON.stringify(summarizeBoard(currentBoard), null, 2)}` + selectionContext
-      : 'No current board (empty start).' + selectionContext
-
-    let conversation: AIMessage[] = [
-      { role: 'user', content: boardContext },
-      ...messages.map<AIMessage>(m => ({
-        role: m.role === 'assistant' ? 'assistant' : 'user',
-        content: m.content
-      }))
-    ]
+    /*
+     * The board and the selection are not pasted into the request any more (screen-pattern §2-2, 2026-10-13): the
+     * whole board went into every turn as a first user message, a second way of knowing the open board beside the
+     * server's line. The model reads what it needs with getBoardOutline · getSelection · findComponents.
+     */
+    let conversation: AIMessage[] = messages.map<AIMessage>(m => ({
+      role: m.role === 'assistant' ? 'assistant' : 'user',
+      content: m.content
+    }))
 
     // multi-turn agentic loop — LLM 이 read 호출 → 서버 실행 → 결과 회신 → LLM 추론 반복.
     // write tool 은 누적해 client 에 patch 로 전달. 본체는 ./agentic-loop 에 분리.
@@ -317,8 +307,7 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
      * 근거집합의 정의와 사정거리는 ./grounding 머리말 참조(식별자 없는 창작 서술은 잡지 못한다). */
     const warnings = checkReplyGrounding(baseReply, {
       systemPrompt,
-      /* 근거집합의 칸 이름은 공용 패키지의 것이다 — 이 값이 보드 문맥이라는 것은 이 파일만 안다. */
-      hostContext: boardContext,
+      /* 보드는 이제 도구로만 모델에게 닿는다 — 읽은 보드는 toolResults 안에 있다(screen-pattern §2-2). */
       messages: messages.map(m => (typeof m.content === 'string' ? m.content : '')),
       toolResults: loopResult.groundedTexts
     })
@@ -331,7 +320,7 @@ export class DefaultBoardAIAssistant implements BoardAIAssistant {
           confidence: { level: warnings.length ? 'low' as const : 'medium' as const, reasons: warnings.length ? ['grounding-warning'] : ['tool-or-board-context'] },
           limitations: warnings.map(code => ({ code })),
           claims: [{ code: patch ? 'board.patch-proposed' : 'board.context-reviewed', severity: 'info' as const, evidence: { toolCalls: toolUsages.length, componentCount: components.length }, method: 'board-agentic-loop', assumptions: ['Board context is current for this turn.'] }],
-          facts: { board: boardContext, toolUsages },
+          facts: { board: summarizeBoard(currentBoard), toolUsages },
           ...(patch ? { proposal: patch } : accumulatedActions.length ? { proposal: accumulatedActions } : {}),
           approvalRequired: true as const,
           approval: { required: true as const, mode: 'confirm' as const, reason: patch || accumulatedActions.length ? 'Board or scene change requires user confirmation.' : 'Analysis is advisory.' },
@@ -449,8 +438,8 @@ Rules:
 배열에 자식을 가질 수 있다. 자식이 또 group 일 수 있어 임의 깊이로 중첩 가능.
 
 가시성:
-  - \`summarizeBoard\` (대화 시작 시 보여지는 보드 상태) 는 *평면 list* 로 모든
-    컴포넌트를 노출한다 — top-level 뿐 아니라 group/container 안 자식도 모두 포함.
+  - \`getBoardOutline\` 은 *평면 list* 로 모든 컴포넌트를 돌려준다 — top-level 뿐 아니라
+    group/container 안 자식도 모두 포함.
   - 자식은 \`_parentRefid\` (부모 group refid) 와 \`_depth\` (중첩 깊이, 0=root) 메타
     가 첨부되어 어느 group 안에 있는지 식별 가능.
   - \`findComponents\` 는 전체 트리를 search — group 안 자식까지 매칭. 특정 group
@@ -640,7 +629,7 @@ Behavioral rules:
 - If the user is asking a question rather than commanding, REPLY in TEXT WITHOUT calling any tool.
 - If the user's request is ambiguous, REPLY in TEXT (asking for clarification) WITHOUT calling any tool.
 - For multiple components, call addComponent multiple times in parallel.
-- The current board JSON is provided as the first user message in the conversation.
+- The board is not in the conversation: read it with \`getBoardOutline\` (all components, flat) and the other read tools before you describe or change it.
 
 Reply formatting rules (chat surface):
 - Reply ONCE with ONE form only. NEVER restate the same answer in a second form (e.g. do NOT add a prose summary after a bullet list, or vice versa).
@@ -713,7 +702,7 @@ export function buildBoardEditTools(knownTypes: string[], exposure: ToolExposure
     {
       name: 'removeComponentByRefid',
       description:
-        'Remove an existing component by its `refid` — the universal numeric handle that things-scene auto-assigns to every component (visible in board summary as the `refid` field of each component).',
+        'Remove an existing component by its `refid` — the universal numeric handle that things-scene auto-assigns to every component (each component in `getBoardOutline` carries it as `refid`).',
       parameters: {
         type: 'object',
         properties: {
@@ -809,6 +798,12 @@ export function buildBoardEditTools(knownTypes: string[], exposure: ToolExposure
       }
     },
     // ── Read tools (서버측 즉시 실행, 결과를 LLM 에 회신) ─────────
+    {
+      name: 'getBoardOutline',
+      description:
+        'The open board as it stands now, saved or not: its own attributes (size, background, ...) and every component in a flat list - group and container children included, each with `refid`, `type`, its key attributes and, for a child, `_parentRefid` / `_depth`. Call this before describing or changing the board. Full details of one component: getComponentByRefid.',
+      parameters: { type: 'object', properties: {} }
+    },
     {
       name: 'getSelection',
       description:
@@ -818,7 +813,7 @@ export function buildBoardEditTools(knownTypes: string[], exposure: ToolExposure
     {
       name: 'getComponentByRefid',
       description:
-        'Get full details of a single component by its `refid` (the things-scene-assigned universal numeric handle). Use this to inspect properties not visible in the board summary.',
+        'Get full details of a single component by its `refid` (the things-scene-assigned universal numeric handle). Use this to inspect properties `getBoardOutline` leaves out.',
       parameters: {
         type: 'object',
         properties: {
@@ -1202,7 +1197,13 @@ export function buildBoardEditTools(knownTypes: string[], exposure: ToolExposure
 
 // ── Read tool 분류 + 실행기 ────────────────────────────────────────
 
+/** How the model learns the board and the selection - by reading, every time it needs to (screen-pattern §2-2). */
+const READ_THE_BOARD =
+  'The board and the selection are not in the conversation. Read the board with `getBoardOutline` before you describe or change it, ' +
+  'and the selection with `getSelection` when the person says "selected", "this" or "these" without naming components; then work only on those.'
+
 const READ_TOOL_NAMES = new Set([
+  'getBoardOutline',
   'getSelection',
   'getComponentByRefid',
   'getComponentStyle',
@@ -1275,6 +1276,9 @@ export function executeReadTool(
   const flatComponents = collectAllComponents(board).map(f => f.component)
 
   switch (call.name) {
+    case 'getBoardOutline':
+      /* The summary that used to be pasted into every request - now read when the question needs it. */
+      return board ? summarizeBoard(board) : { empty: true, message: 'No board is open in this conversation.' }
     case 'getSelection': {
       if (selectedRefids.length === 0) {
         return { selected: [], message: 'No component is currently selected.' }

package/server/service/board-ai-resolver.ts

@@ -10,14 +10,14 @@ import { MoreThan } from 'typeorm'
 import '@things-factory/auth-base'
 
 import { getRepository, rethrowSpoken } from '@things-factory/shell'
-import { aiClientFor, type AgentClient, type AIClient } from '@things-factory/ai-client-base'
+import { aiClientFor, openSubjectLine, type AgentClient, type AIClient } from '@things-factory/ai-client-base'
 import type { ComponentCategory } from '@things-factory/board-import'
 
 import { DefaultBoardAIAssistant } from './assistant.js'
 import { effectiveBoardTools } from './board-tool-rights.js'
 import type { LLMMessage } from './types.js'
 import { ChatSession } from '@things-factory/ai-assistant'
-import { resolveModeSettings, requestTranslator, type ModeSettings } from '@things-factory/ai-assistant'
+import { resolveModeSettings, requestTranslator, splitNextRequest, type ModeSettings } from '@things-factory/ai-assistant'
 import { ChatMessage } from '@things-factory/ai-assistant'
 import { buildLlmHistory } from '@things-factory/ai-assistant'
 import { splitByCap, summaryInstruction } from '@things-factory/ai-assistant'
@@ -207,6 +207,12 @@ class BoardAIChatOutput {
   @Field({ description: 'Conversational reply.' })
   reply: string
 
+  @Field(() => String, {
+    nullable: true,
+    description: 'The request the person is likely to make next, as the reply named it. The input shows it and Tab writes it in. Not stored.'
+  })
+  suggestion?: string | null
+
   @Field(() => GraphQLJSON, { nullable: true, description: 'SceneEditPatch.' })
   patch?: any
 
@@ -452,7 +458,21 @@ export class BoardAIChatResolver {
     const boardTools = await effectiveBoardTools(input.boardTools, context)
     const boardToolsWithheld = input.boardTools !== false && boardTools === false
 
+    /*
+     * The open board - the server's line from the stored anchor, the same door every app's conversation has
+     * (operato-application design/ai/screen-pattern.md §2-1). The board's contents are read with tools.
+     */
+    const openSubject = session
+      ? await openSubjectLine({
+          anchorType: (session as any).anchorType,
+          anchorId: (session as any).anchorId,
+          domain,
+          state: context.state
+        })
+      : undefined
+
     const r = await assistant.chat(llmMessages, input.currentBoard ?? undefined, {
+      openSubject,
       scopes: input.scopes,
       hostContext: input.hostContext ?? undefined,
       surfacePrompt: modeSettings?.systemPrompt,
@@ -474,6 +494,9 @@ export class BoardAIChatResolver {
       toolCallContext: context.state
     })
 
+    /* A reply may end with the next request; the input offers it and the stored answer does not keep it (screen-pattern §4-1). */
+    const { reply, suggestion } = splitNextRequest(r.reply)
+
     // ── Phase C: LLM 호출 후 짧은 DB 쓰기 ─────────────────────────
     let assistantMessageId: string | undefined
     let patchId: string | undefined
@@ -496,7 +519,7 @@ export class BoardAIChatResolver {
       // AI 응답의 #token 들을 currentBoard 에 대해 resolve 한 뒤 inline marker 로 박음.
       // patch 로 새로 만든 컴포넌트는 input.currentBoard 에 없으므로 marker 없이 저장 →
       // 클릭 시 runtime fallback 으로 해석 (그때는 patch 적용 후라 scene 에 존재).
-      const enrichedReply = injectAiMentionRefids(r.reply, input.currentBoard ?? null)
+      const enrichedReply = injectAiMentionRefids(reply, input.currentBoard ?? null)
 
       const aiMsg = await messageRepo.save({
         session: { id: session.id } as any,
@@ -549,7 +572,8 @@ export class BoardAIChatResolver {
     }
 
     return {
-      reply: r.reply,
+      reply,
+      suggestion: suggestion ?? null,
       patch: r.patch ?? null,
       followUp: r.followUp ?? null,
       clientId: base.id,

package/server/service/board-context-path.test.ts

@@ -0,0 +1,32 @@
+/*
+ * The board conversation knows the open board the way every app's conversation does (operato-application
+ * design/ai/screen-pattern.md, ADR-0061 decision 7 exception, ruled 2026-10-13): one server line from the stored
+ * anchor, the contents read with tools, and no second way.
+ */
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+const resolver = readFileSync(join(__dirname, 'board-ai-resolver.ts'), 'utf8')
+const assistant = readFileSync(join(__dirname, 'assistant.ts'), 'utf8')
+
+describe('the board conversation context path', () => {
+  it('★ the open board line is built from the stored session anchor, never from what the screen sent', () => {
+    const block = resolver.slice(resolver.indexOf('const openSubject = session'), resolver.indexOf('const r = await assistant.chat('))
+    expect(block).toMatch(/openSubjectLine\(\{\s+anchorType: \(session as any\)\.anchorType,\s+anchorId: \(session as any\)\.anchorId/)
+    expect(block).not.toMatch(/hostContext|currentBoard/)
+    expect(resolver).toMatch(/assistant\.chat\(llmMessages, input\.currentBoard \?\? undefined, \{\s+openSubject,/)
+  })
+
+  it('★ no whole-board paste is left - the summary is a read tool', () => {
+    expect(assistant).not.toMatch(/Current board state/)
+    expect(assistant).not.toMatch(/role: 'user', content: boardContext/)
+    expect(assistant).toMatch(/case 'getBoardOutline':/)
+  })
+
+  it('★ the stored answer, the list preview and the reply leave out the Next: line', () => {
+    expect(resolver).toMatch(/const \{ reply, suggestion \} = splitNextRequest\(r\.reply\)/)
+    expect(resolver).toMatch(/injectAiMentionRefids\(reply, /)
+    expect(resolver).toMatch(/suggestion: suggestion \?\? null/)
+    expect(resolver).not.toMatch(/injectAiMentionRefids\(r\.reply/)
+  })
+})

package/server/service/types.ts

@@ -25,6 +25,12 @@ export interface ChatOptions {
    * and its tools, and the mode describes the product and the person's work.
    */
   surfacePrompt?: string
+  /**
+   * What the person has open, said by the server each turn from the conversation's stored anchor
+   * (operato-application design/ai/screen-pattern.md §2-1 · ADR-0061 decision 7 exception). The board's
+   * contents are read with the read tools (`getBoardOutline` and the rest), never pasted into the request.
+   */
+  openSubject?: string
   /**
    * 이 대화에 노출할 **외부 도구 카테고리** 화이트리스트(registerToolCategory 이름).
    * 미지정 = 등록된 전부(현행 동작). 성격이 다른 대화면(보드 저작 도크 · 운영 도크)이