@things-factory/ai-assistant 10.1.6 → 10.1.7

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

@@ -67,3 +67,46 @@ export function buildChatMutationInput(args: ChatMutationInputArgs): Record<stri
     ...(args.mentions && args.mentions.length > 0 && { mentions: args.mentions })
   }
 }
+
+/**
+ * Input for `assistantChat` — the door for a surface that has no document of its own.
+ *
+ * Deliberately a separate builder rather than a flag on the one above. The two mutations take
+ * different inputs, and folding them together would mean a board field reaching a surface that
+ * has no board, or a required field going missing with nothing to notice it. The one thing they
+ * share is the conversation, and that is passed the same way.
+ */
+export interface AssistantChatInputArgs {
+  sessionId?: string
+  history: Array<{ role: string; content: string }>
+  /** Who the assistant is on this surface. The host owns this prose; the server appends tool rules. */
+  systemPrompt: string
+  truncateAfterMessageId?: string
+  hostContext?: any
+  toolCategories?: string[]
+  requireGroundingTools?: boolean
+}
+
+/**
+ * Build the neutral input.
+ *
+ * Refuses an empty system prompt instead of sending one. A conversation with no persona still
+ * answers — it just answers as nobody, on a surface that never said what it is — and that reads
+ * as a bad model rather than a missing argument.
+ */
+export function buildAssistantChatInput(args: AssistantChatInputArgs): Record<string, any> {
+  if (!args.systemPrompt?.trim()) {
+    throw new Error('[ox-board-ai-chat] systemPrompt is required when the chat talks to assistantChat')
+  }
+
+  return {
+    sessionId: args.sessionId ?? null,
+    messages: args.history,
+    systemPrompt: args.systemPrompt,
+    ...(args.truncateAfterMessageId ? { truncateAfterMessageId: args.truncateAfterMessageId } : {}),
+    ...(args.hostContext ? { hostContext: args.hostContext } : {}),
+    /* Absent means every registered category; an empty array means none. Both are meant, so pass it through. */
+    ...(args.toolCategories ? { toolCategories: args.toolCategories } : {}),
+    ...(args.requireGroundingTools ? { requireGroundingTools: true } : {})
+  }
+}

package/client/components/chat-triggers.test.ts

@@ -0,0 +1,72 @@
+/*
+ * What this guards: **the empty chat does not teach what this surface cannot do.**
+ *
+ * operato-figure mounted the chat and its empty screen offered all three triggers. `#` mentions
+ * components of a document figure has none of; `/` inserts templates figure registered none of,
+ * so the popup opens empty. Neither errors — they just do nothing, which reads as broken rather
+ * than not applicable.
+ */
+import { availableTriggers } from './chat-triggers'
+
+const chars = (availability: any) => availableTriggers(availability).map(chip => chip.char)
+
+const board = { hasMentionableThings: true, hasSession: true, slashTemplateCount: 12 }
+const figure = { hasMentionableThings: false, hasSession: true, slashTemplateCount: 0 }
+
+describe('a board authoring surface', () => {
+  it('offers all three', () => {
+    expect(chars(board)).toEqual(['#', '@', '/'])
+  })
+})
+
+describe('a surface with no document of its own', () => {
+  it('★ does not offer # — there is nothing to mention', () => {
+    expect(chars(figure)).not.toContain('#')
+  })
+
+  it('★ does not offer / — nobody registered a template, so the popup would open empty', () => {
+    expect(chars(figure)).not.toContain('/')
+  })
+
+  it('still offers @ — mentioning a colleague works wherever a conversation is stored', () => {
+    expect(chars(figure)).toEqual(['@'])
+  })
+})
+
+describe('each chip is read off the one thing it needs', () => {
+  it('a declared type list is enough for # — a live document is not required', () => {
+    expect(chars({ ...figure, hasMentionableThings: true })).toContain('#')
+  })
+
+  it('an ad-hoc turn has no @ — a mention notifies a participant and there is no conversation to join', () => {
+    expect(chars({ ...board, hasSession: false })).not.toContain('@')
+  })
+
+  it('one registered template is enough for /', () => {
+    expect(chars({ ...figure, slashTemplateCount: 1 })).toContain('/')
+  })
+})
+
+describe('what the row looks like when nothing is available', () => {
+  it('★ empty, so the caller can leave the whole row out rather than draw a heading over nothing', () => {
+    expect(availableTriggers({ hasMentionableThings: false, hasSession: false, slashTemplateCount: 0 })).toEqual([])
+  })
+})
+
+describe('order', () => {
+  it('stays # @ / regardless of which ones survive — it is the order people learned', () => {
+    expect(chars({ hasMentionableThings: true, hasSession: false, slashTemplateCount: 3 })).toEqual(['#', '/'])
+  })
+})
+
+describe('every chip carries its own words', () => {
+  it('label and tooltip keys are distinct per chip — one shared key would caption them all alike', () => {
+    const chips = availableTriggers(board)
+    const labels = new Set(chips.map(chip => chip.labelKey))
+    const tooltips = new Set(chips.map(chip => chip.tooltipKey))
+
+    expect(labels.size).toBe(chips.length)
+    expect(tooltips.size).toBe(chips.length)
+    for (const chip of chips) expect(chip.labelKey.startsWith('ai-assistant.')).toBe(true)
+  })
+})

package/client/components/chat-triggers.ts

@@ -0,0 +1,62 @@
+/*
+ * Which trigger characters a chat surface can actually use — **asked, not declared.**
+ *
+ * All three chips (`#` `@` `/`) were always drawn. On operato-figure that taught two things the
+ * surface cannot do: `#` mentions components of a document figure has none of, and `/` inserts
+ * templates figure registered none of, so the popup opens empty.
+ *
+ * A chip that opens nothing is worse than an absent one. The reader does not conclude "not
+ * applicable here" — they conclude the feature is broken, and they are half right.
+ *
+ * So each chip is read off the thing it needs. A host that gains a document, a stored session or
+ * a template set gets the chip with no extra declaration; one that never does never shows it.
+ * Same shape as lite-menu deciding whether the board menu type is selectable by asking whether
+ * its renderer is registered, rather than declaring that it is.
+ */
+
+/** What the surface has to offer, as plain facts. The caller reads these off itself. */
+export interface TriggerAvailability {
+  /** Something to mention: a live document, a static one, or a declared type list. */
+  hasMentionableThings: boolean
+  /** A stored conversation. A `@` mention notifies a participant, and an ad-hoc turn has none. */
+  hasSession: boolean
+  /** How many insertable templates the host registered. */
+  slashTemplateCount: number
+}
+
+export interface TriggerChip {
+  char: '#' | '@' | '/'
+  labelKey: string
+  tooltipKey: string
+}
+
+/** Order is fixed: `#` `@` `/`. It is the order people learned, so it does not follow availability. */
+export function availableTriggers(availability: TriggerAvailability): TriggerChip[] {
+  const chips: TriggerChip[] = []
+
+  if (availability.hasMentionableThings) {
+    chips.push({
+      char: '#',
+      labelKey: 'ai-assistant.label.trigger-component',
+      tooltipKey: 'ai-assistant.text.trigger-component-tooltip'
+    })
+  }
+
+  if (availability.hasSession) {
+    chips.push({
+      char: '@',
+      labelKey: 'ai-assistant.label.trigger-user',
+      tooltipKey: 'ai-assistant.text.trigger-user-tooltip'
+    })
+  }
+
+  if (availability.slashTemplateCount > 0) {
+    chips.push({
+      char: '/',
+      labelKey: 'ai-assistant.label.trigger-insert',
+      tooltipKey: 'ai-assistant.text.trigger-insert-tooltip'
+    })
+  }
+
+  return chips
+}

package/dist-client/components/board-ai-chat.d.ts

@@ -100,6 +100,12 @@ export declare class OxBoardAIChat extends LitElement {
     hostContext?: any;
     /** 코어 보드 편집 도구 사용 여부. 기본 true. 보드를 고칠 이유가 없는 면에서 false. */
     boardTools: boolean;
+    chatEndpoint: 'boardAIChat' | 'assistantChat';
+    /**
+     * Who the assistant is on this surface, in the host's words. Required by `assistantChat`; the
+     * board conversation carries its own persona on the server and ignores this.
+     */
+    systemPrompt?: string;
     /**
      * 라이브 상태를 다루는 대화면인가 — true 면 **첫 턴에 도구 호출을 강제**한다.
      *
@@ -306,6 +312,8 @@ export declare class OxBoardAIChat extends LitElement {
      * 읽었고, 그러면 호스트 값을 한쪽만 반영하는 상태가 만들어질 수 있었다.
      */
     private get exampleGroups();
+    /** 이 표면이 실제로 쓸 수 있는 트리거 — 판정은 `chat-triggers.ts` 가 하고 여기서는 사실만 읽는다. */
+    private get triggerChips();
     private static readonly EXAMPLE_GROUPS;
     /** 보드의 세션 탭 — 다중 세션 활성화 시 패널 상단. host 가 sessions 비워두면 표시 X.
      *  레이블은 session.name 우선, 없으면 fallback "세션 N". */