@things-factory/ai-assistant 10.1.46 → 10.1.50

package/client/utils/assistant-surface.ts

@@ -0,0 +1,157 @@
+/*
+ * What the screen shows - the one way a screen tells the AI dock (design/ai/shared-dock.md §3).
+ *
+ * Before this there were five ways: `context.subject` (warehouse), `BoardEditHost` (twin), `StationAITarget`
+ * (plant), window events (figure) and the board modeller's own panel. The dock now reads one answer:
+ *
+ *   1. an editor that holds a draft provides a surface          provideAssistantSurface(owner, surface)
+ *   2. a page that shows one thing says so in its context        get context() { return { subject: { type, id } } }
+ *      and the app says once how such a subject becomes a surface registerSubjectSurface(type, make)
+ *   3. otherwise the app's home                                   registerAssistantHome(surface)
+ *
+ * The first that answers wins. The dock follows changes through `subscribeAssistantSurface`.
+ */
+import { store } from '@operato/shell'
+
+/** The row a conversation hangs on - its session anchor (ADR-0072 decision 6). */
+export interface AssistantAnchor {
+  anchorType: string
+  anchorId: string
+}
+
+/** No anchor could stand - said to the person as a fact and what to do. */
+export interface AssistantStuck {
+  stuck: string
+  message: string
+}
+
+export type AnchorResult = AssistantAnchor | AssistantStuck
+
+export function isAnchor(result: AnchorResult | undefined): result is AssistantAnchor {
+  return !!result && 'anchorId' in result && !!result.anchorId
+}
+
+/** For a surface that authors a board - the chat gets the board, the dock applies its patches. */
+export interface BoardSurface {
+  currentBoard?: () => any
+  boardProvider?: () => any
+  selectedRefids?: () => number[]
+  knownTypes?: () => string[]
+  categories?: () => any[]
+  componentSchemas?: () => any
+  searchProvider?: (query: string) => any[]
+  applyPatch(detail: any): Promise<{ applied: number; missed: number; note?: string }> | { applied: number; missed: number; note?: string }
+  revertPatch?(patchId: string): Promise<void> | void
+  applyAction?(detail: any): Promise<void> | void
+  /** The chat door for board authoring, until board-ai joins the neutral door (ADR-0061 decision 0-1). */
+  chatEndpoint?: 'boardAIChat' | 'assistantChat'
+}
+
+export interface AssistantSurface {
+  /** Identity - a different key is a different conversation. */
+  key: string
+  /** Matched against the server's mode `subjects` (assistantModes(subject)). */
+  subject: string
+  /** The session anchor, or why none could stand. May ask the server (a row uuid, a domain id). */
+  anchor(): Promise<AnchorResult> | AnchorResult
+  /** Words for the header - never a raw identifier. */
+  label(): string
+  detail?(): string
+  icon?: string
+  /** Read at the moment of sending - never cached, so a draft cannot go stale. */
+  hostContext?(): Record<string, unknown>
+  board?: BoardSurface
+  /** The dock opened another conversation for this surface - e.g. the board modeller records its direct edits under it. */
+  sessionChanged?(sessionId: string): void
+}
+
+type Listener = () => void
+
+const provided = new Map<object, AssistantSurface>()
+let lastOwner: object | undefined
+const subjectMakers = new Map<string, (subject: { type: string; id?: string }) => AssistantSurface>()
+let home: AssistantSurface | undefined
+const listeners = new Set<Listener>()
+
+function changed() {
+  listeners.forEach(listener => {
+    try {
+      listener()
+    } catch {
+      /* one listener's error does not stop the others */
+    }
+  })
+}
+
+/** An editor with a draft says it is on screen. The last one provided wins until it is cleared. */
+export function provideAssistantSurface(owner: object, surface: AssistantSurface): void {
+  provided.set(owner, surface)
+  lastOwner = owner
+  changed()
+}
+
+/** The editor is gone or inactive. A later provider that replaced it is left alone. */
+export function clearAssistantSurface(owner: object): void {
+  if (!provided.delete(owner)) return
+  if (lastOwner === owner) lastOwner = [...provided.keys()].pop()
+  changed()
+}
+
+/** The editor's draft or identity changed - the dock reads it again. */
+export function notifyAssistantSurface(owner: object): void {
+  if (provided.has(owner)) changed()
+}
+
+/** How a page's `context.subject` of this type becomes a surface - declared once by the app. */
+export function registerSubjectSurface(type: string, make: (subject: { type: string; id?: string }) => AssistantSurface): void {
+  subjectMakers.set(type, make)
+  changed()
+}
+
+/** The app's own conversation when the screen shows nothing in particular - a factory, a site, a catalog. */
+export function registerAssistantHome(surface: AssistantSurface): void {
+  home = surface
+  changed()
+}
+
+export function subscribeAssistantSurface(listener: Listener): () => void {
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}
+
+let pageSubjectKey = ''
+let pageSurface: AssistantSurface | undefined
+
+function surfaceFromPage(): AssistantSurface | undefined {
+  const subject = (store.getState() as any)?.route?.context?.subject
+  const type = subject?.type
+  const make = type ? subjectMakers.get(type) : undefined
+  if (!make) return undefined
+  const key = JSON.stringify([type, subject?.id ?? ''])
+  if (key !== pageSubjectKey) {
+    pageSubjectKey = key
+    pageSurface = make({ type, id: subject?.id })
+  }
+  return pageSurface
+}
+
+/** What the dock talks about now: a provided editor, else the page's subject, else the app's home. */
+export function currentAssistantSurface(): AssistantSurface | undefined {
+  return (lastOwner && provided.get(lastOwner)) || surfaceFromPage() || home
+}
+
+/** The app's home surface - for the header's "back to the app's conversation". */
+export function assistantHomeSurface(): AssistantSurface | undefined {
+  return home
+}
+
+/* The page context lives in the store; a page change is a surface change. */
+let lastRouteSubject = ''
+store.subscribe(() => {
+  const subject = (store.getState() as any)?.route?.context?.subject
+  const key = JSON.stringify([subject?.type ?? '', subject?.id ?? ''])
+  if (key !== lastRouteSubject) {
+    lastRouteSubject = key
+    changed()
+  }
+})

package/client/utils/attachment-policy.ts

@@ -0,0 +1,71 @@
+/*
+ * What a conversation accepts as attachments - the screen's copy of the server rule
+ * (server/service/chat-session/attachment-policy.ts, design/ai/shared-dock.md §9-1).
+ *
+ * The screen checks first so the person hears "no" before anything is sent; the door checks again and is
+ * the authority. `test/attachment-policy-agree.test.ts` runs both copies over one table so they cannot drift.
+ */
+
+export type AttachmentKind = 'image' | 'text'
+
+export interface AttachmentPolicy {
+  kinds: AttachmentKind[]
+  maxBytes?: number
+  maxFiles?: number
+}
+
+export const DEFAULT_MAX_BYTES = 5 * 1024 * 1024
+export const DEFAULT_MAX_FILES = 5
+
+const TEXT_TYPES = ['text/plain', 'text/csv', 'text/markdown', 'application/json']
+const TEXT_EXTENSIONS = ['.txt', '.csv', '.md', '.json']
+
+export function attachmentKindOf(file: { type?: string; name?: string }): AttachmentKind | null {
+  const type = (file.type || '').toLowerCase()
+  if (type.startsWith('image/')) return 'image'
+  if (TEXT_TYPES.includes(type)) return 'text'
+  const name = (file.name || '').toLowerCase()
+  if (TEXT_EXTENSIONS.some(ext => name.endsWith(ext))) return 'text'
+  return null
+}
+
+export type AttachmentRefusal =
+  | { code: 'attachments-not-accepted' }
+  | { code: 'attachment-kind-not-accepted'; name: string; kinds: AttachmentKind[] }
+  | { code: 'attachment-too-large'; name: string; maxBytes: number }
+  | { code: 'too-many-attachments'; maxFiles: number }
+
+export function refuseAttachments(
+  policy: AttachmentPolicy | null | undefined,
+  files: { name?: string; type?: string; size?: number }[]
+): AttachmentRefusal | null {
+  if (!files.length) return null
+  if (!policy || !policy.kinds?.length) return { code: 'attachments-not-accepted' }
+
+  const maxFiles = policy.maxFiles ?? DEFAULT_MAX_FILES
+  if (files.length > maxFiles) return { code: 'too-many-attachments', maxFiles }
+
+  const maxBytes = policy.maxBytes ?? DEFAULT_MAX_BYTES
+  for (const file of files) {
+    const kind = attachmentKindOf(file)
+    if (!kind || !policy.kinds.includes(kind)) {
+      return { code: 'attachment-kind-not-accepted', name: file.name || '', kinds: policy.kinds }
+    }
+    if ((file.size ?? 0) > maxBytes) return { code: 'attachment-too-large', name: file.name || '', maxBytes }
+  }
+  return null
+}
+
+/** The file picker's `accept` for a policy. */
+export function acceptOf(policy: AttachmentPolicy | null | undefined): string {
+  const accept: string[] = []
+  if (policy?.kinds?.includes('image')) accept.push('image/*')
+  if (policy?.kinds?.includes('text')) accept.push(...TEXT_EXTENSIONS, ...TEXT_TYPES)
+  return accept.join(',')
+}
+
+/** Where a conversation's file opens - the gated route, under the page's domain path. */
+export function chatAttachmentUrl(sessionId: string, attachmentId: string): string {
+  const domainPath = /^\/domain\/[^/]+/.exec(location.pathname)?.[0] ?? ''
+  return `${domainPath}/chat-attachments/${encodeURIComponent(sessionId)}/${encodeURIComponent(attachmentId)}`
+}

package/dist-client/components/assistant-chat.d.ts

@@ -226,6 +226,12 @@ export declare class OxAssistantChat extends LitElement {
     private attachments;
     /** 드래그 오버 상태 (시각 피드백용) */
     private dragOver;
+    /** This conversation talks to the neutral door - its attachments follow the mode's policy (§9). */
+    private get usesAttachmentPolicy();
+    /** Whether the attach button stands: a mode that declares nothing takes nothing (the board door keeps its images). */
+    private get acceptsAttachments();
+    /** A refusal in the reader's words - the same keys the door uses. */
+    private attachmentRefusalText;
     private onAttachFiles;
     private readFileAsBase64;
     private removeAttachment;

package/dist-client/components/assistant-chat.js

@@ -27,6 +27,7 @@ import { i18next } from '@operato/i18n';
 import { ScrollbarStyles } from '@operato/styles';
 import gql from 'graphql-tag';
 import { renderMarkdown, injectMentionRefids, injectMentionUserIds, stripMentionRefids } from './markdown.js';
+import { acceptOf, chatAttachmentUrl, refuseAttachments } from '../utils/attachment-policy.js';
 import { buildAssistantChatInput, buildChatMutationInput } from './chat-input-builder.js';
 import { receiveRemoteMessage, reconcileSentLine, remoteMessageToLine } from './chat-echo-dedup.js';
 import './mention-popup.js';
@@ -80,6 +81,17 @@ const BOARD_AI_CHAT_MUTATION = gql `
  * front of the model this turn, so a surface that granted a category and sees it missing knows
  * the registration never happened, instead of reading a vague answer as a refusal.
  */
+/* Files go to the conversation first; the turn then names them (design/ai/shared-dock.md §9). */
+const ATTACH_TO_CONVERSATION_MUTATION = gql `
+  mutation AttachToConversation($sessionId: String!, $files: [Upload!]!, $kind: String) {
+    attachToConversation(sessionId: $sessionId, files: $files, kind: $kind) {
+      id
+      name
+      mimetype
+      size
+    }
+  }
+`;
 const ASSISTANT_CHAT_MUTATION = gql `
   mutation AssistantChat($input: AssistantChatInput!) {
     assistantChat(input: $input) {
@@ -133,6 +145,7 @@ const ASSISTANT_MODE_QUERY = gql `
       examples
       footerNotice
       stagedNotice
+      attachments
     }
   }
 `;
@@ -172,6 +185,7 @@ const CHAT_MESSAGES_QUERY = gql `
       relatedPatchId
       toolUsagesJson
       groundingWarningsJson
+      attachmentsJson
       createdAt
       redacted
       creator {
@@ -192,6 +206,7 @@ const CHAT_MESSAGE_SUBSCRIPTION = gql `
       relatedPatchId
       toolUsagesJson
       groundingWarningsJson
+      attachmentsJson
       createdAt
       redacted
       creator {
@@ -405,10 +420,37 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
      * `attachments` 짐 자체는 그대로 둔다: figure 의 도구가 거기서 이미지를 찾는다
      * (`figure-tools.ts` — `ctx.host.image` 가 없을 때의 갈래).
      */
+    /** This conversation talks to the neutral door - its attachments follow the mode's policy (§9). */
+    get usesAttachmentPolicy() {
+        return this.conversation.chatEndpoint === 'assistantChat';
+    }
+    /** Whether the attach button stands: a mode that declares nothing takes nothing (the board door keeps its images). */
+    get acceptsAttachments() {
+        return !this.usesAttachmentPolicy || !!this.modeView?.attachments?.kinds?.length;
+    }
+    /** A refusal in the reader's words - the same keys the door uses. */
+    attachmentRefusalText(refusal) {
+        const params = { ...refusal };
+        if (refusal.code === 'attachment-too-large')
+            params.max = Math.round(refusal.maxBytes / 1024 / 1024);
+        if (refusal.code === 'too-many-attachments')
+            params.max = refusal.maxFiles;
+        if (refusal.code === 'attachment-kind-not-accepted')
+            params.kinds = refusal.kinds.join(', ');
+        return String(i18next.t(`ai-assistant.text.${refusal.code}`, { ...params, defaultValue: refusal.code }));
+    }
     async onAttachFiles(files) {
         if (!files || files.length === 0)
             return;
         const list = Array.from(files);
+        if (this.usesAttachmentPolicy) {
+            /* Said before anything is sent - never cut silently (§9-1). */
+            const refusal = refuseAttachments(this.modeView?.attachments, [...this.attachments, ...list].map(f => ({ name: f.name, type: f.type, size: f.size })));
+            if (refusal) {
+                this.errorMessage = this.attachmentRefusalText(refusal);
+                return;
+            }
+        }
         const newAttachments = [];
         for (const file of list) {
             const id = 'att-' + Math.random().toString(36).substring(2, 9);
@@ -2547,19 +2589,24 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
                 ${line.attachments && line.attachments.length > 0
                     ? html `
                       <div class="msg-attachments">
-                        ${line.attachments.map(att => att.type?.startsWith('image/') || att.url?.startsWith('data:image/') || att.base64
-                        ? html `
-                                <div class="msg-attachment-img-wrap" title=${att.name}>
-                                  <img src=${att.url || att.base64} alt=${att.name} />
+                        ${line.attachments.map(att => {
+                        /* A stored file opens through the conversation's own route (§9-3); a fresh one shows its local copy. */
+                        const href = att.url || att.base64 || (att.id && this.sessionId ? chatAttachmentUrl(this.sessionId, att.id) : '');
+                        /* By type - a text file carries base64 too, and drew as a broken image (found on :3700). */
+                        return att.type?.startsWith('image/') || att.url?.startsWith('data:image/') || att.base64?.startsWith('data:image/')
+                            ? html `
+                                <a class="msg-attachment-img-wrap" title=${att.name} href=${href} target="_blank" rel="noopener">
+                                  <img src=${href} alt=${att.name} />
                                   <span class="msg-attachment-label">${att.name}</span>
-                                </div>
+                                </a>
                               `
-                        : html `
-                                <div class="msg-attachment-file-chip" title=${att.name}>
+                            : html `
+                                <a class="msg-attachment-file-chip" title=${att.name} href=${href || nothing} target="_blank" rel="noopener">
                                   <md-icon>description</md-icon>
                                   <span>${att.name}</span>
-                                </div>
-                              `)}
+                                </a>
+                              `;
+                    })}
                       </div>
                     `
                     : nothing}
@@ -2632,7 +2679,7 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
             id="chat-file-input"
             type="file"
             multiple
-            accept="image/*"
+            accept=${this.usesAttachmentPolicy ? acceptOf(this.modeView?.attachments) : 'image/*'}
             style="display: none"
             @change=${(e) => {
             const input = e.target;
@@ -2642,14 +2689,16 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
             }
         }}
           />
-          <button
-            type="button"
-            class="action"
-            @click=${() => this.renderRoot.querySelector('#chat-file-input')?.click()}
-            title=${i18next.t('ai-assistant.tooltip.attach-file', { defaultValue: 'attach an image (drag & drop or paste supported)' })}>
-            <md-icon>attach_file</md-icon>
-            ${i18next.t('ai-assistant.button.attach', { defaultValue: 'Attach' })}
-          </button>
+          ${this.acceptsAttachments
+            ? html `<button
+                type="button"
+                class="action"
+                @click=${() => this.renderRoot.querySelector('#chat-file-input')?.click()}
+                title=${i18next.t('ai-assistant.tooltip.attach-file', { defaultValue: 'attach an image (drag & drop or paste supported)' })}>
+                <md-icon>attach_file</md-icon>
+                ${i18next.t('ai-assistant.button.attach', { defaultValue: 'Attach' })}
+              </button>`
+            : nothing}
           ${hasMessages
             ? html `
                 <button
@@ -3933,6 +3982,34 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
             }
             this.busy = false;
         }
+        /* The neutral door takes stored files by id: upload them to the conversation first (§9-2). */
+        let attachmentIds;
+        if (attachmentsToSend.length > 0 && this.usesAttachmentPolicy) {
+            if (!this.sessionId) {
+                this.errorMessage = i18next.t('ai-assistant.text.attachments-need-session', { defaultValue: 'attachments need a saved conversation.' });
+                this.attachments = attachmentsToSend;
+                return;
+            }
+            this.busy = true;
+            try {
+                const uploaded = await client.mutate({
+                    mutation: ATTACH_TO_CONVERSATION_MUTATION,
+                    variables: { sessionId: this.sessionId, files: attachmentsToSend.map(a => a.file), kind: this.conversation.kind },
+                    /* The shell's client sends multipart only when asked - without it a File travels as {} and is refused. */
+                    context: { hasUpload: true }
+                });
+                if (uploaded.errors?.length)
+                    throw new Error(uploaded.errors.map(error => error.message).join('\n'));
+                attachmentIds = (uploaded.data?.attachToConversation ?? []).map((file) => file.id);
+            }
+            catch (error) {
+                this.errorMessage = error instanceof Error ? error.message : String(error);
+                this.attachments = attachmentsToSend;
+                this.busy = false;
+                return;
+            }
+            this.busy = false;
+        }
         let requestContext;
         let liveBoard;
         let requestBase;
@@ -3986,7 +4063,7 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
         // 가짜 pending 응답 표시 (UX 부드럽게)
         this.lines = [...this.lines, { role: 'assistant', content: '', pending: true, _localId: asstLocalId }];
         try {
-            if (attachmentsToSend.length > 0) {
+            if (attachmentsToSend.length > 0 && !attachmentIds) {
                 requestContext.hostContext = {
                     ...requestContext.hostContext,
                     attachments: attachmentsToSend.map(a => ({
@@ -4022,7 +4099,8 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
                             history,
                             mode: { kind: this.conversation.kind, target: this.conversation.target },
                             truncateAfterMessageId: this._truncateAfterId,
-                            hostContext: requestContext.hostContext
+                            hostContext: requestContext.hostContext,
+                            attachmentIds
                         })
                         : buildChatMutationInput({
                             sessionId: this.sessionId,
@@ -4039,7 +4117,9 @@ let OxAssistantChat = class OxAssistantChat extends LitElement {
                             categories: this.categories,
                             componentSchemas: this.componentSchemas,
                             selectedRefids: this.selectedRefids ?? [],
-                            mentions
+                            mentions,
+                            /* With a declared mode the server owns persona and tools; the board door still carries the board. */
+                            mode: this.conversation.kind ? { kind: this.conversation.kind, target: this.conversation.target } : undefined
                         })
                 }
             });