@things-factory/ai-assistant 10.1.26 → 10.1.28

package/server/service/assistant-mode/registry.test.ts

@@ -0,0 +1,105 @@
+/*
+ * What this guards: a conversation's character is the server's, not the caller's.
+ *
+ * Until 2026-09-18 the door took `systemPrompt`, `toolCategories`, `model`, `temperature`,
+ * `maxTokens` and `requireGroundingTools` from the request, so anyone holding
+ * `ai-assistant:mutation` could rewrite the assistant's persona, open any registered tool
+ * category and name an expensive model. ADR-0061 decision 7: the app server registers the mode
+ * kinds and the client sends `kind` + `target` + `hostContext`.
+ *
+ * The registry is also where a mode's promises are checked against what it can actually do:
+ * a `/` sentence that needs a tool the mode does not expose is ADR-0058 decision 3's defect, and
+ * it is caught at registration rather than when a person presses it.
+ */
+import { clearAssistantModes, getAssistantMode, getAssistantModeWarnings, listAssistantModes, registerAssistantMode } from './registry'
+
+import { clearToolRegistry, registerToolCategory } from '@things-factory/ai-client-base'
+
+const spec = (over: Partial<Parameters<typeof registerAssistantMode>[0]> = {}) => ({
+  kind: 'twin.space',
+  systemPrompt: 'you answer about one space',
+  toolCategories: ['twin-ops'],
+  ...over
+})
+
+beforeEach(() => {
+  clearAssistantModes()
+  clearToolRegistry()
+  registerToolCategory({
+    name: 'twin-ops',
+    guidance: 'call getSpace before answering about a space',
+    specs: [{ kind: 'read', name: 'getSpace', description: 'read one space', schema: {}, builder: () => async () => ({}) } as any]
+  } as any)
+})
+
+it('★ a registered mode is found by kind, and carries what the server owns', () => {
+  registerAssistantMode(spec({ model: 'claude-sonnet-5', maxTokens: 2048, requireToolOnFirstTurn: true }))
+
+  const found = getAssistantMode('twin.space')
+
+  expect(found?.systemPrompt).toBe('you answer about one space')
+  expect(found?.toolCategories).toEqual(['twin-ops'])
+  expect(found?.model).toBe('claude-sonnet-5')
+  expect(found?.maxTokens).toBe(2048)
+  expect(found?.requireToolOnFirstTurn).toBe(true)
+})
+
+it('★ an unknown kind is absent — the door must refuse, not fall back to a default', () => {
+  registerAssistantMode(spec())
+
+  expect(getAssistantMode('twin.nothing')).toBeUndefined()
+})
+
+it('a kind that is not <app>.<surface> is refused at registration', () => {
+  expect(() => registerAssistantMode(spec({ kind: 'twinspace' }))).toThrow(/<app>\.<surface>/)
+  expect(() => registerAssistantMode(spec({ kind: 'Twin.Space' }))).toThrow(/<app>\.<surface>/)
+})
+
+it('a mode with no system prompt is refused — the persona is what the server owns', () => {
+  expect(() => registerAssistantMode(spec({ systemPrompt: '  ' }))).toThrow(/systemPrompt/)
+})
+
+it('★ registering the same kind twice is refused — two declarations of one conversation disagree', () => {
+  registerAssistantMode(spec())
+
+  expect(() => registerAssistantMode(spec({ systemPrompt: 'a different persona' }))).toThrow(/already registered/)
+  expect(getAssistantMode('twin.space')?.systemPrompt).toBe('you answer about one space')
+})
+
+it('★ a slash sentence that needs a tool the mode does not expose is reported by code at boot', () => {
+  registerAssistantMode(
+    spec({
+      slashTemplates: [
+        { name: 'summarize', descriptionKey: 'twin.slash.summarize', templateKey: 'twin.slash.summarize.template', tools: ['getSpace'] },
+        { name: 'place', descriptionKey: 'twin.slash.place', templateKey: 'twin.slash.place.template', tools: ['proposeSceneEdit'] }
+      ]
+    })
+  )
+
+  const warnings = getAssistantModeWarnings()
+
+  expect(warnings).toHaveLength(1)
+  expect(warnings[0].code).toBe('assistant-mode-slash-outside-tools')
+  expect(warnings[0].params).toEqual({ kind: 'twin.space', slash: 'place', tool: 'proposeSceneEdit' })
+})
+
+it('the same check reads the tools registered after the mode — boot order must not decide it', () => {
+  registerAssistantMode(spec({ slashTemplates: [{ name: 'place', descriptionKey: 'k', templateKey: 't', tools: ['proposeSceneEdit'] }] }))
+  expect(getAssistantModeWarnings()).toHaveLength(1)
+
+  registerToolCategory({
+    name: 'twin-authoring',
+    guidance: 'propose an edit, never apply it',
+    specs: [{ kind: 'read', name: 'proposeSceneEdit', description: 'propose', schema: {}, builder: () => async () => ({}) } as any]
+  } as any)
+  registerAssistantMode(spec({ kind: 'twin.board', toolCategories: ['twin-ops', 'twin-authoring'], slashTemplates: [{ name: 'place', descriptionKey: 'k', templateKey: 't', tools: ['proposeSceneEdit'] }] }))
+
+  expect(getAssistantModeWarnings().map(w => w.params.kind)).toEqual(['twin.space'])
+})
+
+it('listing returns the modes in registration order', () => {
+  registerAssistantMode(spec())
+  registerAssistantMode(spec({ kind: 'twin.board' }))
+
+  expect(listAssistantModes().map(m => m.kind)).toEqual(['twin.space', 'twin.board'])
+})

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

@@ -0,0 +1,147 @@
+/**
+ * The mode registry — one place that knows what each conversation is.
+ *
+ * Registration refuses what cannot be true later: a kind that is not `<app>.<surface>` (the door
+ * looks a mode up by that name), an empty persona (the field this whole change exists to take off
+ * the wire), and a second declaration of a kind that is already declared — two declarations of one
+ * conversation disagree, and the one that wins would be whichever module booted last.
+ *
+ * What it does not refuse is a `/` sentence naming a tool the mode does not expose. That check
+ * reads the tool registry, which fills up as modules boot, so it runs when asked rather than at
+ * registration: `getAssistantModeWarnings()` is the answer as of now, and the boot report reads it
+ * after every module is in.
+ */
+import { getToolSpecsFor } from '@things-factory/ai-client-base'
+
+import type { AssistantModeSpec, AssistantModeWarning } from './types'
+
+const modes = new Map<string, AssistantModeSpec>()
+
+const KIND = /^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$/
+
+export function registerAssistantMode(spec: AssistantModeSpec): void {
+  if (!KIND.test(String(spec?.kind ?? ''))) {
+    throw new Error(
+      `[ai-assistant/assistant-mode] '${spec?.kind}' is not a mode kind. Use <app>.<surface> in lowercase — ` +
+        "'twin.space', 'plant.station', 'figure.modeller'. The client names the conversation by this."
+    )
+  }
+
+  if (!String(spec.systemPrompt ?? '').trim()) {
+    throw new Error(
+      `[ai-assistant/assistant-mode] mode '${spec.kind}' has no systemPrompt. Who the assistant is on a ` +
+        'surface belongs to the server that owns the surface (ADR-0061 decision 7).'
+    )
+  }
+
+  if (modes.has(spec.kind)) {
+    throw new Error(
+      `[ai-assistant/assistant-mode] mode '${spec.kind}' is already registered. Two declarations of one ` +
+        'conversation disagree, and which one wins would depend on boot order. Give the second one its own kind.'
+    )
+  }
+
+  modes.set(spec.kind, spec)
+}
+
+export function getAssistantMode(kind: string): AssistantModeSpec | undefined {
+  return modes.get(kind)
+}
+
+export function listAssistantModes(): ReadonlyArray<AssistantModeSpec> {
+  return Array.from(modes.values())
+}
+
+/**
+ * The promises a mode makes that its tools cannot keep, as of now.
+ *
+ * Read after boot: a mode may register before the category its slash sentences use.
+ */
+export function getAssistantModeWarnings(): ReadonlyArray<AssistantModeWarning> {
+  const out: AssistantModeWarning[] = []
+
+  /*
+   * 한 화면이 어느 대화를 기본으로 여는가 — 등록 순서로 정하지 않는다(ADR-0072 A17 ②). 없으면 화면이
+   * 무엇을 열지 모르고, 둘이면 마지막에 부팅한 모듈이 조용히 이긴다. 둘 다 여기서 말한다.
+   */
+  const defaults = new Map<string, string[]>()
+  const claimed = new Set<string>()
+  for (const mode of modes.values()) {
+    for (const subject of mode.subjects ?? []) claimed.add(subject)
+    for (const subject of mode.defaultFor ?? []) {
+      defaults.set(subject, [...(defaults.get(subject) ?? []), mode.kind])
+    }
+  }
+  for (const subject of claimed) {
+    const owners = defaults.get(subject) ?? []
+    if (owners.length === 0) {
+      out.push({
+        code: 'assistant-mode-subject-without-default',
+        params: { kind: '', subject },
+        message: `no conversation is the default for subject '${subject}' — a screen showing it has nothing to open`
+      })
+    } else if (owners.length > 1) {
+      out.push({
+        code: 'assistant-mode-subject-default-twice',
+        params: { kind: owners[0], subject, kinds: owners },
+        message: `subject '${subject}' has more than one default (${owners.join(', ')}) — boot order would decide it`
+      })
+    }
+  }
+
+  for (const mode of modes.values()) {
+    /*
+     * 고를 수 있는 대화에는 부를 이름이 있어야 한다 — 고르개에 종류 이름(`twin.space`)이 뜨면 그것은
+     * 우리 내부 단위를 사람에게 떠넘기는 것이다.
+     */
+    const shared = (mode.subjects ?? []).some(subject => countModesFor(subject) > 1)
+    if (shared && !mode.labelKey) {
+      out.push({
+        code: 'assistant-mode-offered-without-label',
+        params: { kind: mode.kind },
+        message: `mode '${mode.kind}' can be offered beside another on the same subject but has no labelKey`
+      })
+    }
+  }
+
+  for (const mode of modes.values()) {
+    const exposed = new Set(getToolSpecsFor(mode.toolCategories ?? []).map(spec => spec.name))
+    for (const slash of mode.slashTemplates ?? []) {
+      for (const tool of slash.tools ?? []) {
+        if (exposed.has(tool)) continue
+        out.push({
+          code: 'assistant-mode-slash-outside-tools',
+          params: { kind: mode.kind, slash: slash.name, tool },
+          message:
+            `mode '${mode.kind}' offers '/${slash.name}', which needs '${tool}' — not in its tool categories ` +
+            `[${(mode.toolCategories ?? []).join(', ')}]. The person presses it and the model answers without doing it.`
+        })
+      }
+    }
+  }
+  return out
+}
+
+/** 이 subject 종류에 서는 대화가 몇인가 — 고르개가 필요한지, 이름이 필요한지를 가른다. */
+function countModesFor(subject: string): number {
+  let count = 0
+  for (const mode of modes.values()) {
+    if ((mode.subjects ?? []).includes(subject)) count++
+  }
+  return count
+}
+
+/**
+ * 이 subject 종류에 서는 대화들 — 등록 순서대로, 기본이 먼저.
+ *
+ * 화면은 이 목록으로 고르개를 낸다. 하나뿐이면 고르개를 내지 않는다(ADR-0072 A17 ①).
+ */
+export function assistantModesForSubject(subject: string): ReadonlyArray<AssistantModeSpec> {
+  const standing = [...modes.values()].filter(mode => (mode.subjects ?? []).includes(subject))
+  return standing.sort((a, b) => Number((b.defaultFor ?? []).includes(subject)) - Number((a.defaultFor ?? []).includes(subject)))
+}
+
+/** Test only. */
+export function clearAssistantModes(): void {
+  modes.clear()
+}

package/server/service/assistant-mode/resolve.test.ts

@@ -0,0 +1,78 @@
+/*
+ * What this guards: the two things the door does with a mode — take the conversation's settings
+ * from the server's declaration, and hand the screen its words already translated.
+ *
+ * A caller naming a kind nobody registered must be refused. Falling back to "a plain conversation"
+ * would answer with no persona and no tools, and the screen would show an answer as though the
+ * mode had been honoured (ADR-0053: no silent "none").
+ */
+import { clearAssistantModes, registerAssistantMode } from './registry'
+import { assistantModeView, resolveModeSettings } from './resolve'
+
+/** Stands in for `context.t` — returns the key and params so the test can see what was translated. */
+const t = (key: string, params?: Record<string, any>) => `t(${key}${params?.count !== undefined ? `,${params.count}` : ''})`
+
+beforeEach(() => {
+  clearAssistantModes()
+  registerAssistantMode({
+    kind: 'twin.space',
+    systemPrompt: 'you answer about one space',
+    toolCategories: ['twin-ops'],
+    requireToolOnFirstTurn: true,
+    model: 'claude-sonnet-5',
+    maxTokens: 2048,
+    temperature: 0.2,
+    slashTemplates: [{ name: 'summarize', descriptionKey: 'twin.slash.summarize', templateKey: 'twin.slash.summarize.template' }],
+    catalogEntries: [{ id: 'space', label: 'space' }],
+    footerNoticeKey: 'twin.notice.footer',
+    stagedNoticeKey: 'twin.notice.staged'
+  })
+})
+
+it('★ the settings come from the registered mode', () => {
+  const settings = resolveModeSettings({ kind: 'twin.space', target: 'S-12' }, t)
+
+  expect(settings).toEqual({
+    systemPrompt: 'you answer about one space',
+    toolCategories: ['twin-ops'],
+    requireToolOnFirstTurn: true,
+    model: 'claude-sonnet-5',
+    temperature: 0.2,
+    maxTokens: 2048
+  })
+})
+
+it('★ an unregistered kind is refused — no plain-conversation fallback', () => {
+  expect(() => resolveModeSettings({ kind: 'twin.nothing' }, t)).toThrow(/t\(ai-assistant.text.unknown-mode\)/)
+  try {
+    resolveModeSettings({ kind: 'twin.nothing' }, t)
+  } catch (error: any) {
+    expect(error.code).toBe('unknown-assistant-mode')
+    expect(error.params).toEqual({ kind: 'twin.nothing' })
+  }
+})
+
+it('★ a request with no mode is refused — the door has no default conversation', () => {
+  expect(() => resolveModeSettings(undefined as any, t)).toThrow()
+})
+
+it('★ the screen gets sentences, not keys — the server translates (ADR-0054)', () => {
+  const view = assistantModeView('twin.space', t)
+
+  expect(view.slashTemplates).toEqual([
+    { name: 'summarize', description: 't(twin.slash.summarize)', template: 't(twin.slash.summarize.template)' }
+  ])
+  expect(view.footerNotice).toBe('t(twin.notice.footer)')
+  expect(view.stagedNotice).toBe('t(twin.notice.staged)')
+  expect(view.catalogEntries).toEqual([{ id: 'space', label: 'space' }])
+})
+
+it('a mode that declares no wording gets empty lists, not undefined holes', () => {
+  registerAssistantMode({ kind: 'twin.board', systemPrompt: 'you edit the open board' })
+
+  const view = assistantModeView('twin.board', t)
+
+  expect(view.slashTemplates).toEqual([])
+  expect(view.catalogEntries).toEqual([])
+  expect(view.footerNotice).toBeUndefined()
+})

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

@@ -0,0 +1,96 @@
+/**
+ * What the door and the screen each take from a mode.
+ *
+ * Both start from the same declaration, so a screen cannot show `/` sentences for a conversation
+ * the server would answer differently.
+ */
+import { getAssistantMode } from './registry'
+import type { AssistantModeSlash } from './types'
+
+export type Translate = (key: string, params?: Record<string, any>) => string
+
+export interface AssistantModeRef {
+  /** Which conversation this is — a registered `<app>.<surface>`. */
+  kind: string
+  /** What it is about. Part of the conversation's lifetime; the tools read it, not the settings. */
+  target?: string
+}
+
+/**
+ * A kind nobody registered. The sentence is the person's (ADR-0054); the code and the kind are for
+ * whoever reads the log — a screen naming a conversation the server does not have is a mismatched
+ * deployment, not something the person did.
+ */
+function unknownModeError(kind: string, t: Translate): Error {
+  const error: any = new Error(
+    t('ai-assistant.text.unknown-mode', {
+      defaultValue: 'this screen asked for a conversation this server does not have ({kind}). reload the page.',
+      kind: kind || '—'
+    })
+  )
+  error.code = 'unknown-assistant-mode'
+  error.params = { kind }
+  return error
+}
+
+export interface ModeSettings {
+  systemPrompt: string
+  toolCategories?: string[]
+  requireToolOnFirstTurn?: boolean
+  model?: string
+  temperature?: number
+  maxTokens?: number
+}
+
+/** The conversation's settings, from the server's declaration. */
+export function resolveModeSettings(ref: AssistantModeRef, t: Translate): ModeSettings {
+  const kind = String(ref?.kind ?? '')
+  const mode = kind ? getAssistantMode(kind) : undefined
+
+  if (!mode) throw unknownModeError(kind, t)
+
+  return {
+    systemPrompt: mode.systemPrompt,
+    toolCategories: mode.toolCategories,
+    requireToolOnFirstTurn: mode.requireToolOnFirstTurn,
+    model: mode.model,
+    temperature: mode.temperature,
+    maxTokens: mode.maxTokens
+  }
+}
+
+export interface AssistantModeSlashView {
+  name: string
+  description: string
+  template: string
+}
+
+export interface AssistantModeView {
+  kind: string
+  slashTemplates: AssistantModeSlashView[]
+  catalogEntries: any[]
+  proposalChoices: any[]
+  placeholder?: string
+  footerNotice?: string
+  stagedNotice?: string
+}
+
+/** What the screen shows, in the words of the request's locale. */
+export function assistantModeView(kind: string, t: Translate): AssistantModeView {
+  const mode = getAssistantMode(kind)
+  if (!mode) throw unknownModeError(kind, t)
+
+  return {
+    kind: mode.kind,
+    slashTemplates: (mode.slashTemplates ?? []).map((slash: AssistantModeSlash) => ({
+      name: slash.name,
+      description: t(slash.descriptionKey),
+      template: t(slash.templateKey)
+    })),
+    catalogEntries: mode.catalogEntries ?? [],
+    proposalChoices: mode.proposalChoices ?? [],
+    placeholder: mode.placeholderKey ? t(mode.placeholderKey) : undefined,
+    footerNotice: mode.footerNoticeKey ? t(mode.footerNoticeKey) : undefined,
+    stagedNotice: mode.stagedNoticeKey ? t(mode.stagedNoticeKey) : undefined
+  }
+}

package/server/service/assistant-mode/subject-defaults.test.ts

@@ -0,0 +1,86 @@
+/*
+ * 화면이 무엇을 여는가 — ADR-0072 A17 ②.
+ *
+ * 한 subject 종류에 기본 대화가 없거나 둘이면 화면이 여는 대화는 부팅 순서가 정한다. 그것은 화면을
+ * 열어봐야 알 수 있고, 모듈 하나가 늘면 소리 없이 바뀐다. 부팅 보고가 말하게 하고, 여기서 셋 다
+ * 문다.
+ */
+import {
+  assistantModesForSubject,
+  clearAssistantModes,
+  getAssistantModeWarnings,
+  registerAssistantMode
+} from './registry'
+
+const persona = 'you are here'
+
+describe('assistant mode — subjects and defaults', () => {
+  beforeEach(() => clearAssistantModes())
+  afterAll(() => clearAssistantModes())
+
+  it('★ a subject nobody claims as default is a boot warning, not a silent pick', () => {
+    registerAssistantMode({ kind: 'twin.space', systemPrompt: persona, subjects: ['space'] })
+
+    const codes = getAssistantModeWarnings().map(w => w.code)
+    expect(codes).toContain('assistant-mode-subject-without-default')
+  })
+
+  it('★ two defaults on one subject is a boot warning — boot order must not decide it', () => {
+    registerAssistantMode({
+      kind: 'twin.space',
+      systemPrompt: persona,
+      subjects: ['board'],
+      defaultFor: ['board'],
+      labelKey: 'a'
+    })
+    registerAssistantMode({
+      kind: 'twin.authoring',
+      systemPrompt: persona,
+      subjects: ['board'],
+      defaultFor: ['board'],
+      labelKey: 'b'
+    })
+
+    const twice = getAssistantModeWarnings().find(w => w.code === 'assistant-mode-subject-default-twice')
+    expect(twice?.params.kinds).toEqual(['twin.space', 'twin.authoring'])
+  })
+
+  it('★ a conversation offered beside another needs something to call it', () => {
+    registerAssistantMode({
+      kind: 'twin.space',
+      systemPrompt: persona,
+      subjects: ['board'],
+      defaultFor: ['board'],
+      labelKey: 'twin.ai.mode.space'
+    })
+    registerAssistantMode({ kind: 'twin.authoring', systemPrompt: persona, subjects: ['board'] })
+
+    const unnamed = getAssistantModeWarnings().find(w => w.code === 'assistant-mode-offered-without-label')
+    expect(unnamed?.params.kind).toBe('twin.authoring')
+  })
+
+  it('one conversation alone on its subject needs no label — there is nothing to choose between', () => {
+    registerAssistantMode({
+      kind: 'plant.station',
+      systemPrompt: persona,
+      subjects: ['station'],
+      defaultFor: ['station']
+    })
+
+    expect(getAssistantModeWarnings()).toEqual([])
+  })
+
+  it('the default comes first, so a screen can open the list head without knowing the rule', () => {
+    registerAssistantMode({ kind: 'twin.authoring', systemPrompt: persona, subjects: ['board'], labelKey: 'b' })
+    registerAssistantMode({
+      kind: 'twin.space',
+      systemPrompt: persona,
+      subjects: ['board'],
+      defaultFor: ['board'],
+      labelKey: 'a'
+    })
+
+    expect(assistantModesForSubject('board').map(m => m.kind)).toEqual(['twin.space', 'twin.authoring'])
+    expect(assistantModesForSubject('nothing-shows-this')).toEqual([])
+  })
+})

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

@@ -0,0 +1,103 @@
+/**
+ * What a conversation is, declared by the app server that owns the screen (ADR-0061 decision 7).
+ *
+ * ADR-0058 put these five in one value so they could not fall out of step, but the value lived in
+ * the browser and travelled on every request: the persona, the tool categories, the model and the
+ * limits were the caller's to choose. A caller choosing its own tool categories is a caller
+ * choosing its own authority, so the declaration moved here and the client sends only which one it
+ * is talking in (`kind`) and what about (`target`).
+ */
+
+/** A `/` sentence this mode offers, and what it needs to be answerable. */
+export interface AssistantModeSlash {
+  /** Short name shown in the list. */
+  name: string
+  /** i18n key for the one-line description. The server translates it into the request's locale. */
+  descriptionKey: string
+  /** i18n key for the sentence that lands in the input. */
+  templateKey: string
+  /**
+   * The tools this sentence needs. A mode must not offer work it cannot do (ADR-0058 decision 3),
+   * and a name outside `toolCategories` is reported at boot rather than when a person presses it.
+   */
+  tools?: string[]
+}
+
+export interface AssistantModeSpec {
+  /** `<app>.<surface>` — `twin.space`, `plant.station`, `figure.modeller`. */
+  kind: string
+
+  /**
+   * Which kinds of subject this conversation stands for — `['board', 'space']` (ADR-0072 A17 ①).
+   *
+   * A screen says what it is showing (`context.subject`), and these say which conversations that
+   * subject can carry. It is a list of types and not a predicate on purpose: a list can be counted
+   * at boot and pinned by a test, while a function can only be run.
+   *
+   * On the twin modeller nothing could be asked about operations, because an open board pinned the
+   * authoring conversation and that conversation opens one category. A conversation that also
+   * stands for `board` is how the same screen carries both.
+   */
+  subjects?: string[]
+
+  /**
+   * The conversation a screen opens when the person has not chosen — one per subject type
+   * (ADR-0072 A17 ②).
+   *
+   * Registration order must not decide this: whichever module booted last would silently become
+   * the default. Exactly one mode declares each subject type, and the boot report says so when a
+   * type has none or more than one.
+   */
+  defaultFor?: string[]
+
+  /**
+   * i18n key for what this conversation is called where a person chooses between them —
+   * "이 그림 고치기", "이 현장 지금 어때". A mode a screen may offer needs one.
+   */
+  labelKey?: string
+  /** Who the assistant is here, and what it must not claim to do. The server's, not the caller's. */
+  systemPrompt: string
+  /** Which tool categories this conversation may use. Absent or empty exposes none. */
+  toolCategories?: string[]
+  /** Make the model read before it answers — for surfaces whose subject is live state. */
+  requireToolOnFirstTurn?: boolean
+  /** Model and limits are policy, not a request field. */
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  /** What `/` offers. Declared as keys; the server translates. */
+  slashTemplates?: AssistantModeSlash[]
+  /** What `@` offers. */
+  catalogEntries?: any[]
+  /**
+   * i18n key for the words in the empty input.
+   *
+   * The screen says what this conversation is for, and that differs by mode: figure's modeller had
+   * "describe the figure you want" while the person was there to change the figure already open.
+   */
+  placeholderKey?: string
+  /** i18n key for the line under an empty conversation. */
+  footerNoticeKey?: string
+  /** i18n key for the line shown once the host reports a proposal staged. */
+  stagedNoticeKey?: string
+  /** Follow-up chips for a proposal that arrived without its own. */
+  proposalChoices?: any[]
+}
+
+/** A declaration that registered but is not what the contract asks for. Code + params, not prose. */
+export interface AssistantModeWarning {
+  /**
+   * `assistant-mode-slash-outside-tools` — a `/` sentence needs a tool this mode does not open.
+   * `assistant-mode-subject-without-default` — a subject type no conversation claims as its default.
+   * `assistant-mode-subject-default-twice` — two conversations claim the same subject type.
+   * `assistant-mode-offered-without-label` — a conversation a screen may offer with nothing to call it.
+   */
+  code:
+    | 'assistant-mode-slash-outside-tools'
+    | 'assistant-mode-subject-without-default'
+    | 'assistant-mode-subject-default-twice'
+    | 'assistant-mode-offered-without-label'
+  params: { kind: string; slash?: string; tool?: string; subject?: string; kinds?: string[] }
+  /** For a person reading the boot log; callers act on the code and params. */
+  message: string
+}