@things-factory/ai-assistant 10.1.26 → 10.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.26",
+  "version": "10.1.28",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -29,10 +29,10 @@
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.26",
-    "@things-factory/auth-base": "^10.1.26",
+    "@things-factory/ai-client-base": "^10.1.28",
+    "@things-factory/auth-base": "^10.1.28",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.26",
+    "@things-factory/shell": "^10.1.28",
     "dompurify": "^3.0.0",
     "graphql-scalars": "^1.22.0",
     "graphql-tag": "^2.12.6",
@@ -44,5 +44,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "151bda14d899442c6846532ddded1e2bfe23a2f5"
+  "gitHead": "3a260a0f79bc6b41a692a103955bfcc541aff60e"
 }

package/server/explicit-graphql-types.test.ts

@@ -0,0 +1,56 @@
+/*
+ * 모든 문이 **자기 형을 명시하는가** — 빠지면 부팅이 죽는다.
+ *
+ * ── 왜 이 시험이 있나 ──────────────────────────────────────────────────────
+ * `chatMessageActivity` 를 async 로 바꾸자(받는 사람마다 가리기 — ADR-0073 판정 1) 반환형이
+ * `Promise<ChatMessage>` 가 되었고, type-graphql 의 reflection 은 Promise 안을 못 본다. 스키마를
+ * 세울 때 NoExplicitTypeError 가 나고 **패키지 적재 자체가 실패한다** — 시험이 아니라 서버가 죽는다.
+ * 컴파일은 통과하므로 타입검사도 못 잡는다. plant 레인이 설치본을 올리다 잡아 알려 주었다(2026-09-18).
+ *
+ * ── 왜 스키마를 안 세우고 글자를 읽나 ─────────────────────────────────────
+ * 이 꾸러미의 시험기는 babel 이라 데코레이터 metadata 가 없다. 스키마를 세우면 리플렉션이 없어 전부
+ * 같은 오류가 나고, 그러면 이 시험은 아무것도 못 가른다. 대신 선언을 읽는다 — 데코레이터가 형을
+ * 인자로 받고 있는지만 본다. 그것이 빠진 자리가 정확히 터지는 자리다.
+ */
+import { readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+const root = join(__dirname, 'service')
+
+function sources(dir: string): { path: string; text: string }[] {
+  const out: { path: string; text: string }[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...sources(path))
+    else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')) {
+      out.push({ path, text: readFileSync(path, 'utf-8') })
+    }
+  }
+  return out
+}
+
+/** `@Query(`, `@Mutation(`, `@Subscription(` 바로 다음 글자가 형을 주고 있나. */
+function untyped(): string[] {
+  const out: string[] = []
+  for (const { path, text } of sources(root)) {
+    for (const match of text.matchAll(/@(Query|Mutation|Subscription)\(\s*([^\n]*)/g)) {
+      const [, kind, rest] = match
+      /* 형을 주는 두 모양: `() => X` 와 `type => X`. 그 밖은 옵션 객체부터 시작한 것이다. */
+      if (/^\(\s*\)\s*=>/.test(rest) || /^\w+\s*=>/.test(rest)) continue
+      const line = text.slice(0, match.index).split('\n').length
+      out.push(`${path.slice(root.length + 1)}:${line} @${kind}`)
+    }
+  }
+  return out
+}
+
+describe('every GraphQL door names its type', () => {
+  it('★ 형을 안 준 Query/Mutation/Subscription 이 없다 — 있으면 부팅에서 터진다', () => {
+    expect(untyped()).toEqual([])
+  })
+
+  it('이 시험이 실제로 문들을 보고 있다 — 정규식이 소스와 어긋나면 0건으로 조용히 통과한다', () => {
+    const doors = sources(root).flatMap(s => [...s.text.matchAll(/@(Query|Mutation|Subscription)\(/g)])
+    expect(doors.length).toBeGreaterThan(20)
+  })
+})

package/server/service/assistant-capability-resolver.ts

@@ -0,0 +1,66 @@
+/*
+ * One window for one question: what state is this deployment's AI in.
+ *
+ * Two things were being answered by failure or by a log line — whether a provider is configured at
+ * all (standard A7-a), and which registrations are not yet what the contracts ask for (A1 stage one,
+ * and the modes' `/` sentences). They are the same question asked by different people, so they come
+ * back together, as codes.
+ *
+ * A screen reads this **before** offering to ask the assistant. It is a query: reading what a
+ * deployment can do is reading.
+ */
+import { Ctx, Directive, Field, ObjectType, Query, Resolver } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import '@things-factory/auth-base'
+
+import { aiCapability, getToolRegistryWarnings } from '@things-factory/ai-client-base'
+
+import { getAssistantModeWarnings } from './assistant-mode/index.js'
+
+@ObjectType({ description: 'A registration that was accepted but is not yet what the contract asks for.' })
+class AiRegistrationWarning {
+  @Field({ description: 'What is missing, as a code — never prose a screen has to parse.' })
+  code: string
+
+  @Field(() => GraphQLJSON, { description: 'Which registration it is about (category, tool, mode, slash).' })
+  params: any
+
+  @Field({ description: 'The same thing in a sentence, for whoever reads a boot log.' })
+  message: string
+}
+
+@ObjectType({ description: "Whether this deployment has an AI, and what its registrations are missing." })
+class AiCapabilityView {
+  @Field({ description: "'configured' or 'not-configured'. A screen that has not asked yet knows a third state of its own: it does not know." })
+  state: string
+
+  @Field({ nullable: true, description: 'Which provider answers.' })
+  provider?: string
+
+  @Field({ nullable: true, description: 'The default model this deployment would use.' })
+  model?: string
+
+  @Field({ nullable: true, description: 'Why it is not configured: no-config · no-provider · unknown-provider · no-adapter.' })
+  reason?: string
+
+  @Field(() => [AiRegistrationWarning], { description: 'Tools with no declared privilege, and modes offering work their tools cannot do.' })
+  warnings: AiRegistrationWarning[]
+}
+
+@Resolver()
+export class AssistantCapabilityResolver {
+  @Query(() => AiCapabilityView, {
+    description: 'Whether this deployment has an AI configured, and which registrations are incomplete. Read this before offering to ask the assistant — do not find out by failing.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
+  async aiCapability(@Ctx() _context: any): Promise<AiCapabilityView> {
+    const capability = aiCapability()
+    const warnings = [...getToolRegistryWarnings(), ...getAssistantModeWarnings()].map(warning => ({
+      code: warning.code,
+      params: warning.params,
+      message: warning.message
+    }))
+
+    return { ...capability, warnings } as AiCapabilityView
+  }
+}

package/server/service/assistant-chat-resolver.ts

@@ -28,16 +28,32 @@ import '@things-factory/auth-base'
 
 import { config } from '@things-factory/env'
 import { getRepository } from '@things-factory/shell'
-import { createAIClient, getDefaultAIClient, registryAssistantChat, type AIClient } from '@things-factory/ai-client-base'
+import {
+  createAIClient,
+  findToolSpec,
+  getDefaultAIClient,
+  registryAssistantChat,
+  type AIClient
+} from '@things-factory/ai-client-base'
 
 import { ChatSession } from './chat-session/chat-session.js'
 import { assertStationSession } from './chat-session/station-session-guard.js'
 import { ChatMessage } from './chat-message/chat-message.js'
 import { buildLlmHistory } from './chat-message/llm-history.js'
+import { splitByCap } from './chat-message/history-summary.js'
+import { foldSessionHistory } from './chat-message/fold-session-history.js'
+import { groundingSourcesFor } from './grounding-sources.js'
 import { publishChatMessage } from './chat-message/chat-message-publish.js'
 import { publishSessionActivity } from './chat-session/session-activity-publish.js'
 import { activityPatch, autoSessionName } from './chat-session/session-inbox.js'
 import { toolAccessFor } from './tool-access.js'
+import { ChatSessionParticipant } from './chat-session-participant/chat-session-participant.js'
+import { doorsForAnswer } from './chat-message/message-doors.js'
+import { readerGate } from './chat-message/reader-gate.js'
+import { inviteMentionedUsers } from './chat-session-participant/mention-invite.js'
+import { buildInviteNotification } from './chat-session-participant/invite-notification.js'
+import { resolveModeSettings } from './assistant-mode/resolve.js'
+import { requestTranslator } from './request-translator.js'
 
 /**
  * How many stored messages reach the model.
@@ -57,6 +73,19 @@ class AssistantMessageInput {
   content: string
 }
 
+@InputType({ description: 'Which conversation this is, and what it is about.' })
+class AssistantModeInput {
+  @Field({ description: 'A mode kind the app server registered — `<app>.<surface>`, e.g. "twin.space".' })
+  kind: string
+
+  @Field({
+    nullable: true,
+    description:
+      'What this conversation is about — the space, the station, the model being edited. With `kind` it is the conversation\'s lifetime: when either changes the screen closes the conversation and starts another.'
+  })
+  target?: string
+}
+
 @InputType({ description: 'One turn of a conversation that has no document of its own.' })
 class AssistantChatInput {
   @Field({
@@ -71,18 +100,11 @@ class AssistantChatInput {
   })
   messages: AssistantMessageInput[]
 
-  @Field({
+  @Field(() => AssistantModeInput, {
     description:
-      'Who the assistant is on this surface, in the words of the product that owns the screen. The rules for using each tool come from whoever registered it and are appended by the server.'
+      'Which conversation this is. The persona, the tool categories, the model and the limits come from the mode the app server registered (ADR-0061 decision 7) — a caller choosing its own tool categories would be a caller choosing its own authority.'
   })
-  systemPrompt: string
-
-  @Field(() => [String], {
-    nullable: true,
-    description:
-      'Registered tool categories this conversation may use (registerToolCategory names, e.g. ["figure-authoring"]). Omitted or empty allows none — a plain conversation. A tool that declares a privilege is offered only to a caller who holds it.'
-  })
-  toolCategories?: string[]
+  mode: AssistantModeInput
 
   @Field(() => GraphQLJSON, {
     nullable: true,
@@ -98,21 +120,6 @@ class AssistantChatInput {
   })
   truncateAfterMessageId?: string
 
-  @Field({
-    nullable: true,
-    description:
-      'Require a tool call before the model may answer. For surfaces that report live state, where an unchecked assertion reads the same as a checked one.'
-  })
-  requireGroundingTools?: boolean
-
-  @Field({ nullable: true, description: 'Model identifier override. Falls back to the configured default.' })
-  model?: string
-
-  @Field({ nullable: true, description: 'Sampling temperature override.' })
-  temperature?: number
-
-  @Field({ nullable: true, description: 'Max output tokens per call.' })
-  maxTokens?: number
 }
 
 @ObjectType()
@@ -132,6 +139,13 @@ class AssistantChatOutput {
   @Field({ nullable: true, description: 'Stored ChatMessage id of the reply.' })
   assistantMessageId?: string
 
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description:
+      'Set when this turn did not fit: { omitted, summarized } — how many earlier messages the model did not see, and whether a summary stood in for them. Without it the person watches the conversation lose its beginning in silence, while the model is told.'
+  })
+  historyFolded?: any
+
   @Field(() => GraphQLJSON, {
     nullable: true,
     description: 'Tool usages during the turn — {name, arguments, result, kind}. The surface shows them foldably.'
@@ -194,6 +208,14 @@ export class AssistantChatResolver {
       )
     }
 
+    /*
+     * Read the declaration before anything is stored. A kind this server does not have is a
+     * mismatched deployment, and the person should see that instead of a conversation with no
+     * persona and no tools.
+     */
+    const t = requestTranslator(context)
+    const settings = resolveModeSettings(input.mode, t)
+
     const { domain, user } = context.state
     const sessionRepo = getRepository(ChatSession)
     const messageRepo = getRepository(ChatMessage)
@@ -203,15 +225,23 @@ export class AssistantChatResolver {
       const found = await sessionRepo.findOneBy({ id: input.sessionId, domain: { id: domain.id } as any })
       if (!found) throw new Error(`ChatSession ${input.sessionId} not found`)
       if (found.anchorType === 'figure' && input.hostContext?.figureId !== found.anchorId) {
-        throw new Error('이 대화는 다른 Figure의 이력입니다. 현재 모델의 대화를 다시 여세요.')
+        throw new Error(
+          context.t('ai-assistant.text.other-figure-history', {
+            defaultValue: 'this conversation belongs to another figure. open the conversation of the model you have open.'
+          })
+        )
       }
       if (found.anchorType === 'application' && (input.hostContext?.app !== found.anchorId || input.hostContext?.figureId)) {
-        throw new Error('애플리케이션 대화와 모델 대화를 구분해서 다시 여세요.')
+        throw new Error(
+          context.t('ai-assistant.text.application-vs-model-history', {
+            defaultValue: 'this conversation is about the application, not about a model. open the one you want.'
+          })
+        )
       }
       session = found
     }
 
-    assertStationSession(session, input.hostContext)
+    assertStationSession(session, input.hostContext, t)
 
     const lastUserMessage = input.messages[input.messages.length - 1]
     let userMessageId: string | undefined
@@ -225,6 +255,12 @@ export class AssistantChatResolver {
         session: { id: session.id } as any,
         role: 'user',
         content: lastUserMessage.content,
+        /*
+         * This door is the one people call to ask the assistant, so a turn stored here was for the
+         * assistant (ADR-0070 A15 decision ①). The value comes from which door was called, never
+         * from the request — two sources for one fact can disagree.
+         */
+        addressee: 'assistant',
         creator: user,
         updater: user,
         parentMessage: previousLast ? ({ id: previousLast.id } as any) : undefined
@@ -244,6 +280,27 @@ export class AssistantChatResolver {
         /* noop */
       }
 
+      /*
+       * 사람이 `@이름` 으로 부른 사람은 이 대화에 들어온다(ADR-0071 결정 1). 이 문은 **사람의 턴**을
+       * 저장하는 문이라 그 일을 한다 — 모델의 답이나 도구 결과는 아무도 초대하지 않는다.
+       */
+      const invite = await inviteMentionedUsers({
+        content: lastUserMessage.content,
+        sessionId: session.id!,
+        domainId: domain.id,
+        inviter: user,
+        participants: getRepository(ChatSessionParticipant),
+        visibility: (session as any).visibility
+      })
+      if (invite.invited.length > 0) {
+        const payload = buildInviteNotification(invite.invited, undefined, user)
+        try {
+          if (payload) await (context.state as any)?.notify?.(payload)
+        } catch {
+          /* 편지가 못 갔다고 방에 들어온 사실이 취소되지는 않는다. */
+        }
+      }
+
       publishChatMessage({ domainId: domain.id, sessionId: session.id, message: saved } as any)
       publishSessionActivity({
         domainId: domain.id,
@@ -256,13 +313,52 @@ export class AssistantChatResolver {
       })
     }
 
+    /*
+     * 이번 턴에 상한 밖으로 밀려난 것이 있는가 — 화면이 「대화가 길어졌다」를 알릴 근거다.
+     *
+     * 이 문은 그 사실을 내지 않았다. 대화창에는 그 안내를 그리는 자리가 있고(`historyFolded`), 보드
+     * 문만 그 값을 채웠다. 그래서 앱의 대화는 앞부분이 잘려 나가도 **사람에게는 아무 말도 하지 않았다** —
+     * 모델에게는 「N 개 생략」을 적어 보내면서.
+     */
+    const readRows = session
+      ? await messageRepo.find({
+          where: { session: { id: session.id } as any },
+          order: { createdAt: 'ASC' },
+          relations: ['creator']
+        })
+      : []
+    /*
+     * 모델이 읽는 이력도 **부른 사람** 기준으로 가린다 — ADR-0073 판정 1. 가리지 않으면, 문을 한 번도
+     * 안 지난 사람이 "아까 그 수 다시 말해 줘" 한 마디로 값을 가져간다. 모델이 옮겨 적는 순간 그 값은
+     * 문 없는 새 답이 된다. 가린 자리를 지우지 않고 한 줄로 남기는 이유도 같다 — 지우면 모델이 그런
+     * 말이 없었다고 답하고, 그것은 거짓말이다.
+     */
+    const storedRows = await readerGate(context)(readRows)
+    const capped = splitByCap(
+      storedRows.map(row => ({ id: row.id, role: row.role, content: row.content ?? '' })),
+      LLM_HISTORY_MAX_TURNS
+    )
+    const historyFolded =
+      capped.dropped.length > 0
+        ? { omitted: capped.dropped.length, summarized: Boolean((session as any)?.lastSummary) }
+        : undefined
+
     const conversation = session
       ? buildLlmHistory(
-          await messageRepo.find({
-            where: { session: { id: session.id } as any },
-            order: { createdAt: 'ASC' },
-            relations: ['creator']
-          }),
+          /*
+           * The model reads who spoke and who they spoke to. The entity carries the speaker as a
+           * relation and the addressee as a column; the history wants them as plain fields, and
+           * without this mapping every line arrived unattributed — a room of people read as one
+           * voice (ADR-0070 A15 decision ②).
+           */
+          storedRows.map(message => ({
+            id: message.id,
+            role: message.role,
+            content: message.content,
+            senderId: (message as any).creator?.id,
+            senderName: (message as any).creator?.name,
+            addressee: (message as any).addressee
+          })),
           {
             maxTurns: LLM_HISTORY_MAX_TURNS,
             truncateAfterMessageId: input.truncateAfterMessageId,
@@ -291,23 +387,51 @@ export class AssistantChatResolver {
     const result = await registryAssistantChat({
       client,
       messages: conversation as any,
-      systemPrompt: input.systemPrompt,
-      toolCategories: input.toolCategories,
+      systemPrompt: settings.systemPrompt,
+      toolCategories: settings.toolCategories,
       toolAccess: toolAccessFor(context),
+      /* The stop notice is a sentence a person reads — the server writes it in their language (ADR-0054). */
+      t,
       hostContext: input.hostContext,
+      /*
+       * 근거는 도구 결과만이 아니다 — 시스템 프롬프트 · 이 대화의 말 · 화면이 보낸 스냅숏도 근거다
+       * (`ai-client-base/utils/grounding`). 이 문은 그 셋을 넘기지 않아, **사람이 방금 타이핑한
+       * 식별자**를 되받아 적은 답이 「근거 없음」으로 표시됐다. 그런 경고가 몇 번 나오면 사람이 경고
+       * 자체를 안 보게 된다.
+       */
+      groundingSources: groundingSourcesFor({
+        systemPrompt: settings.systemPrompt,
+        messages: conversation as any,
+        hostContext: input.hostContext
+      }),
       state: context.state,
-      model: input.model,
-      temperature: input.temperature,
-      maxTokens: input.maxTokens,
-      requireToolOnFirstTurn: input.requireGroundingTools
+      model: settings.model,
+      temperature: settings.temperature,
+      maxTokens: settings.maxTokens,
+      requireToolOnFirstTurn: settings.requireToolOnFirstTurn
     })
 
+    /*
+     * 이 답이 지나온 문 — ADR-0073 판정 1. 행에도, 목록 미리보기에도 같은 값이 간다. 한쪽만 적으면
+     * 가려진 답이 목록에는 그대로 뜬다.
+     */
+    const answerDoors = doorsForAnswer(
+      (result.loop.toolUsages ?? []).map((usage: any) => usage?.name).filter(Boolean),
+      name => (findToolSpec(name, settings.toolCategories) as any)?.doors
+    )
+
     let assistantMessageId: string | undefined
     if (session) {
       const stored = await messageRepo.save({
         session: { id: session.id } as any,
         role: 'assistant',
         content: result.reply,
+        /*
+         * 이 답이 지나온 문을 함께 적는다 — ADR-0073 판정 1. 방은 도메인 안에서 공개이므로, 이 문장이
+         * 실어 나르는 값을 나중에 읽는 사람이 열 수 있는지 판정할 근거가 행에 있어야 한다. 적지 않으면
+         * 빈 목록이 되고, 빈 목록은 누구나 읽는다는 뜻이다.
+         */
+        doors: answerDoors,
         toolUsages: result.loop.toolUsages?.length ? JSON.stringify(result.loop.toolUsages) : undefined,
         groundingWarnings: result.groundingWarnings?.length ? JSON.stringify(result.groundingWarnings) : undefined,
         creator: user,
@@ -331,8 +455,25 @@ export class AssistantChatResolver {
       await sessionRepo.update(session.id!, {
         aiClientId: client.id,
         updater: user,
-        ...activityPatch(result.reply)
+        ...activityPatch(result.reply, new Date(), answerDoors)
       } as any)
+
+      /*
+       * 상한 밖으로 밀려난 앞부분을 요약으로 접는다 — **답을 돌려준 뒤**에 한다(사용자 대기 시간에
+       * 요약 호출을 얹지 않는다). 기다리지 않으므로 실패해도 대화에는 영향이 없다: 요약이 없으면 다음
+       * 턴이 「N 개 생략」으로 정직하게 알린다.
+       *
+       * 이 문에는 이 호출이 없었다. 조각은 다 있었는데(상한 · 생략 알림 · `lastSummary` · 순수 규칙)
+       * 부르는 쪽이 보드 제품 하나뿐이어서, 앱의 대화는 며칠이 지나도 앞부분을 요약하지 않고 매 턴
+       * 「생략했다」고만 말했다 — 협의가 길어질수록 처음에 합의한 것이 먼저 사라진다.
+       */
+      void foldSessionHistory({
+        sessionId: session.id!,
+        domainId: domain.id,
+        client,
+        maxTurns: LLM_HISTORY_MAX_TURNS,
+        locale: context.state?.locale
+      })
     }
 
     return {
@@ -344,7 +485,8 @@ export class AssistantChatResolver {
       toolUsages: result.loop.toolUsages?.length ? result.loop.toolUsages : null,
       offeredTools: result.offeredTools,
       proposals: result.loop.proposals?.length ? result.loop.proposals : null,
-      groundingWarnings: result.groundingWarnings?.length ? result.groundingWarnings : null
+      groundingWarnings: result.groundingWarnings?.length ? result.groundingWarnings : null,
+      historyFolded: historyFolded ?? null
     }
   }
 }

package/server/service/assistant-mode/assistant-mode-resolver.ts

@@ -0,0 +1,102 @@
+/*
+ * The screen asks what its conversation offers.
+ *
+ * The `/` sentences, the `@` catalog and the two notices used to travel from the browser into the
+ * request, which meant the screen and the door could describe the same conversation differently.
+ * They are declared once, in the mode, as i18n keys — and this query hands them over already
+ * written in the request's locale (ADR-0054, and the same rule A11 applied to the stop notice).
+ * The persona, the tool categories and the limits stay on the server: nothing here returns them.
+ */
+import { Arg, Ctx, Directive, Field, ObjectType, Query, Resolver } from 'type-graphql'
+import { GraphQLJSON } from 'graphql-scalars'
+import '@things-factory/auth-base'
+
+import { assistantModeView } from './resolve.js'
+import { assistantModesForSubject } from './registry.js'
+import { requestTranslator } from '../request-translator.js'
+
+@ObjectType({ description: 'One `/` sentence, in the words of this request.' })
+class AssistantModeSlashView {
+  @Field({ description: 'Short name shown in the list.' })
+  name: string
+
+  @Field({ description: 'One line about what it does.' })
+  description: string
+
+  @Field({ description: 'The sentence that lands in the input.' })
+  template: string
+}
+
+@ObjectType({ description: 'What a conversation offers on screen.' })
+class AssistantModeView {
+  @Field({ description: 'The mode kind this describes.' })
+  kind: string
+
+  @Field(() => [AssistantModeSlashView], { description: 'What `/` offers.' })
+  slashTemplates: AssistantModeSlashView[]
+
+  @Field(() => GraphQLJSON, { description: 'What `@` offers.' })
+  catalogEntries: any[]
+
+  @Field(() => GraphQLJSON, { description: 'Follow-up chips for a proposal that arrived without its own.' })
+  proposalChoices: any[]
+
+  @Field({ nullable: true, description: 'What the empty input says — what this conversation is for.' })
+  placeholder?: string
+
+  @Field({ nullable: true, description: 'The line under an empty conversation.' })
+  footerNotice?: string
+
+  @Field({ nullable: true, description: 'The line shown once the host reports a proposal staged.' })
+  stagedNotice?: string
+}
+
+@ObjectType({ description: 'A conversation a screen may open for what it is showing.' })
+class AssistantModeChoice {
+  @Field({ description: 'The mode kind to open.' })
+  kind: string
+
+  @Field({ description: 'What to call it where a person chooses — already in the words of this request.' })
+  label: string
+
+  @Field({ description: 'Whether this is the one to open when the person has not chosen.' })
+  isDefault: boolean
+}
+
+@Resolver()
+export class AssistantModeResolver {
+  /*
+   * 이 화면이 보여 주는 것으로 열 수 있는 대화들 — ADR-0072 A17 ①.
+   *
+   * 화면은 자기가 무엇을 보여 주는지(`subject`)만 안다. 그 위에 어느 대화가 서는지는 앱 서버가
+   * 선언한다. 화면이 종류 목록을 손으로 들고 있으면, 대화를 하나 더 세운 날 그 화면만 모른 채로 남는다.
+   *
+   * 하나만 오면 고르개를 내지 않는다 — 고를 것이 없는 고르개는 자리만 차지한다.
+   */
+  @Query(() => [AssistantModeChoice], {
+    description:
+      'Conversations that stand for this kind of subject, the default first. A screen showing one subject opens the head of this list and offers the rest; a single entry means there is nothing to choose.'
+  })
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
+  async assistantModes(@Arg('subject') subject: string, @Ctx() context: any): Promise<AssistantModeChoice[]> {
+    const t = requestTranslator(context)
+
+    return assistantModesForSubject(subject).map(mode => ({
+      kind: mode.kind,
+      /*
+       * 이름이 없는 대화는 종류를 그대로 쓴다. 부팅 보고가 이미 그것을 경고로 말하므로 여기서 숨기지
+       * 않는다 — 화면에 `twin.space` 가 뜨면 그것이 빠진 선언을 가리킨다.
+       */
+      label: mode.labelKey ? t(mode.labelKey) : mode.kind,
+      isDefault: (mode.defaultFor ?? []).includes(subject)
+    }))
+  }
+  @Query(() => AssistantModeView, {
+    description: 'What this conversation offers on screen — `/` sentences, the `@` catalog and the notices, translated.'
+  })
+  /* Reading what a conversation offers is reading, and the same door the session list uses. */
+  @Directive('@privilege(category: "ai-assistant", privilege: "query")')
+  async assistantMode(@Arg('kind') kind: string, @Ctx() context: any): Promise<AssistantModeView> {
+    return assistantModeView(kind, requestTranslator(context)) as AssistantModeView
+  }
+}

package/server/service/assistant-mode/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Modes — what each conversation is, declared by the app server that owns the screen.
+ *
+ * Design: ADR-0061 decision 7 (`operato-twin/design/04-decisions.md`) and the AI standard's A2.
+ */
+export {
+  registerAssistantMode,
+  getAssistantMode,
+  listAssistantModes,
+  assistantModesForSubject,
+  getAssistantModeWarnings,
+  clearAssistantModes
+} from './registry.js'
+export { resolveModeSettings, assistantModeView } from './resolve.js'
+export type { AssistantModeSpec, AssistantModeSlash, AssistantModeWarning } from './types.js'
+export type { AssistantModeRef, ModeSettings, AssistantModeView, AssistantModeSlashView, Translate } from './resolve.js'