@things-factory/ai-assistant 10.1.47 → 10.1.50

package/client/components/assistant-dock.ts

@@ -0,0 +1,617 @@
+import '@material/web/icon/icon.js'
+import './assistant-chat.js'
+import './assistant-session-toolbar.js'
+import './assistant-session-manager.js'
+
+import gql from 'graphql-tag'
+import { LitElement, css, html, nothing, type TemplateResult } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+import { keyed } from 'lit/directives/keyed.js'
+
+import { client } from '@operato/graphql'
+import { i18next, localize } from '@operato/i18n'
+import { closeOverlay, notify } from '@operato/layout'
+import { OxPrompt } from '@operato/popup'
+import { AppController, store } from '@operato/shell'
+import { ScrollbarStyles } from '@operato/styles'
+
+import { followPickedConversation, type AssistantMode } from './assistant-mode.js'
+import { AssistantSessionController, type AssistantSession, type AssistantSessionTarget } from '../utils/assistant-session-controller.js'
+import { assistantSessionTransport } from '../utils/assistant-session-transport.js'
+import { readAiCapability } from '../utils/assistant-capability-read.js'
+import type { AiCapability } from '../utils/assistant-capability.js'
+import { setOpenSession, subscribeSessionActivity } from '../utils/assistant-activity.js'
+import {
+  assistantHomeSurface,
+  currentAssistantSurface,
+  isAnchor,
+  subscribeAssistantSurface,
+  type AnchorResult,
+  type AssistantSurface
+} from '../utils/assistant-surface.js'
+import { runProposal, type ProposalContext, type ProposalOutcome } from '../utils/assistant-proposals.js'
+import { subscribeAssistantAsk, takeAssistantAsk, type AssistantAsk } from '../utils/assistant-ask.js'
+
+export const ASSISTANT_DOCK_VIEWPART = 'assistant-dock'
+
+const t = (key: string, defaultValue: string, options: Record<string, unknown> = {}) =>
+  i18next.t(`ai-assistant.dock.${key}`, { defaultValue, ...options })
+
+const MODES_QUERY = gql`
+  query ($subject: String!) {
+    assistantModes(subject: $subject) {
+      kind
+      label
+      isDefault
+    }
+  }
+`
+
+async function modesFor(subject: string): Promise<{ kind: string; label?: string; isDefault?: boolean }[]> {
+  const response = await client.query({ query: MODES_QUERY, variables: { subject }, fetchPolicy: 'network-only' })
+  if (response.errors?.length) throw new Error(response.errors[0].message)
+  return response.data?.assistantModes ?? []
+}
+
+/**
+ * The AI dock - the same in every operato application (design/ai/shared-dock.md).
+ *
+ * ── What is here and what is not ────────────────────────────────────────────────
+ *   here      where it stands, whether an AI answers, which surface and anchor, which conversation (mode),
+ *             sessions and their management, unread, proposals and their outcome, asks from other screens
+ *   the app   what its screens show (surfaces, assistant-surface.ts), how its proposal kinds apply
+ *             (assistant-proposals.ts), and on the server its modes and tools
+ *
+ * Nothing in this file names an application or a proposal kind. A behaviour one app needs and another does
+ * not is a surface field or a handler, never a branch here.
+ */
+@customElement('ox-assistant-dock')
+export class AssistantDock extends localize(i18next)(LitElement) {
+  static styles = [
+    ScrollbarStyles,
+    css`
+      :host {
+        display: flex;
+        flex-direction: column;
+        width: 420px;
+        max-width: 100vw;
+        box-sizing: border-box;
+        height: 100%;
+        min-height: 0;
+        background: var(--md-sys-color-surface-container-lowest);
+        border-left: 1px solid var(--md-sys-color-outline-variant);
+        color: var(--md-sys-color-on-surface);
+        font-size: 13px;
+      }
+
+      /* Below 1440px the page keeps its full width and only the dock floats. The DOM stays - the chat does not reconnect. */
+      @media (max-width: 1439.98px) {
+        :host {
+          position: fixed;
+          inset: 0 0 0 auto;
+          height: 100vh;
+          height: 100dvh;
+          z-index: 10;
+          box-shadow: var(--md-sys-elevation-shadow-3, -4px 0 16px rgb(0 0 0 / 20%));
+        }
+      }
+
+      @media (max-width: 599.98px) {
+        :host {
+          width: 100vw;
+        }
+      }
+
+      .scope {
+        display: flex;
+        align-items: center;
+        gap: 6px;
+        min-height: 40px;
+        padding: 5px 8px;
+        border-bottom: 1px solid var(--md-sys-color-outline-variant);
+      }
+
+      .scope > md-icon {
+        --md-icon-size: 18px;
+        flex: none;
+        color: var(--md-sys-color-primary);
+      }
+
+      .what {
+        display: grid;
+        flex: 1;
+        min-width: 0;
+        font-size: 12px;
+        font-weight: 650;
+        line-height: 1.25;
+      }
+
+      .what span {
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+
+      .detail {
+        color: var(--md-sys-color-on-surface-variant);
+        font-size: 10.5px;
+        font-weight: 400;
+      }
+
+      .sbtn {
+        display: inline-flex;
+        align-items: center;
+        flex: none;
+        padding: 4px;
+        border: none;
+        border-radius: 8px;
+        background: none;
+        color: var(--md-sys-color-on-surface-variant);
+        cursor: pointer;
+      }
+
+      .sbtn:hover {
+        background: var(--md-sys-color-surface-container-high);
+        color: var(--md-sys-color-on-surface);
+      }
+
+      .sbtn md-icon {
+        --md-icon-size: 18px;
+      }
+
+      ox-assistant-session-toolbar {
+        flex: none;
+        min-width: 0;
+        padding: 3px 8px;
+        border-bottom: 1px solid var(--md-sys-color-outline-variant);
+        --border-color: var(--md-sys-color-outline-variant);
+        --main-section-background-color: var(--md-sys-color-surface-container);
+        --primary-color: var(--md-sys-color-primary);
+        font: inherit;
+        font-size: 12px;
+      }
+
+      ox-assistant-chat,
+      ox-assistant-session-manager {
+        flex: 1;
+        min-height: 0;
+      }
+
+      /* No conversation could stand - say what stopped it, never an empty panel. */
+      .stuck {
+        margin: auto;
+        padding: 20px;
+        text-align: center;
+        line-height: 1.7;
+        color: var(--md-sys-color-on-surface-variant);
+      }
+
+      .stuck .sbtn {
+        margin-top: 6px;
+        gap: 4px;
+        font: inherit;
+      }
+    `
+  ]
+
+  /** The viewpart this dock lives in - for closing it. */
+  @property({ type: String }) viewpart = ASSISTANT_DOCK_VIEWPART
+
+  @state() private capability: AiCapability = 'unknown'
+  @state() private asked = false
+  @state() private surface?: AssistantSurface
+  @state() private anchor?: AnchorResult
+  @state() private kind = ''
+  /** kind → its label, for the manager's rows. */
+  @state() private kindLabels: Record<string, string> = {}
+  @state() private sessions: AssistantSession[] = []
+  @state() private sessionId = ''
+  @state() private loading = false
+  @state() private failure = ''
+  @state() private showingHistory = false
+  @state() private conversationView = 0
+  @state() private asking?: { ask?: string; draft?: string; requestId: string }
+
+  private app = new AppController(this)
+  /** The kind the person picked; kept while the surface stays the same. */
+  private chosenKind = ''
+  private revision = 0
+  /** What the conversation was opened for - a send is refused when the screen moved on. */
+  private openedFor = ''
+  private unsubscribers: (() => void)[] = []
+  private controller = new AssistantSessionController(
+    assistantSessionTransport,
+    next => {
+      if (next.sessionId !== this.sessionId) {
+        setOpenSession(next.sessionId)
+        this.surface?.sessionChanged?.(next.sessionId)
+      }
+      this.sessions = next.sessions
+      this.sessionId = next.sessionId
+      this.loading = next.loading
+      this.failure = next.error
+    },
+    { getItem: key => sessionStorage.getItem(key), setItem: (key, value) => sessionStorage.setItem(key, value) },
+    { lazy: true }
+  )
+
+  private onStartNewSession = () => void this.newConversation()
+
+  connectedCallback() {
+    super.connectedCallback()
+    this.addEventListener('assistant-start-new-session', this.onStartNewSession)
+    this.unsubscribers.push(
+      subscribeAssistantSurface(() => this.follow()),
+      subscribeAssistantAsk(() => void this.takeAsk()),
+      subscribeSessionActivity(activity => {
+        /* A rename or a new conversation elsewhere on this anchor - the tabs read again. */
+        if (activity.kind === 'meta' && isAnchor(this.anchor) && activity.anchorId === this.anchor.anchorId) void this.reloadSessions()
+      })
+    )
+    this.follow(true)
+  }
+
+  disconnectedCallback() {
+    this.revision++
+    this.removeEventListener('assistant-start-new-session', this.onStartNewSession)
+    this.unsubscribers.splice(0).forEach(unsubscribe => unsubscribe())
+    setOpenSession('')
+    this.controller.clear()
+    super.disconnectedCallback()
+  }
+
+  private scopeKey(surface = this.surface) {
+    return JSON.stringify([this.app.contextPath, surface?.key ?? ''])
+  }
+
+  /** The screen changed - a different surface or domain is a different conversation. */
+  private follow(force = false) {
+    const next = currentAssistantSurface()
+    if (!force && next === this.surface && this.scopeKey(next) === this.openedFor) return
+    if (next?.key !== this.surface?.key) this.chosenKind = ''
+    this.surface = next
+    void this.open()
+  }
+
+  private async open(): Promise<void> {
+    const ticket = ++this.revision
+    this.conversationView++
+    this.showingHistory = false
+    void this.controller.open(undefined)
+    this.loading = true
+    this.failure = ''
+    this.anchor = undefined
+    this.openedFor = this.scopeKey()
+
+    try {
+      if (this.capability !== 'configured') {
+        this.capability = await readAiCapability()
+        this.asked = true
+      }
+      if (ticket !== this.revision || this.capability !== 'configured') return
+
+      const surface = this.surface
+      if (!surface) return
+
+      const anchor = await surface.anchor()
+      if (ticket !== this.revision) return
+      this.anchor = anchor
+      if (!isAnchor(anchor)) return
+
+      const modes = await modesFor(surface.subject)
+      if (ticket !== this.revision) return
+      this.kindLabels = Object.fromEntries(modes.map(mode => [mode.kind, mode.label || mode.kind]))
+      const chosen = modes.find(mode => mode.kind === this.chosenKind) ?? modes.find(mode => mode.isDefault) ?? modes[0]
+      this.kind = chosen?.kind ?? ''
+      if (!this.kind) {
+        this.anchor = { stuck: 'no-conversation', message: t('no-conversation', 'there is no conversation for this screen.') }
+        return
+      }
+
+      const user = (store.getState() as any).auth?.user
+      const userId = user?.id || user?.email
+      if (!userId) throw new Error(t('no-user', 'your sign-in could not be read. sign in again.'))
+
+      await this.controller.open(this.target(userId, anchor))
+      await this.takeAsk()
+    } catch (error) {
+      if (ticket === this.revision) this.failure = (error as Error).message
+    } finally {
+      if (ticket === this.revision) this.loading = false
+    }
+  }
+
+  private target(userId: string, anchor: { anchorType: string; anchorId: string }): AssistantSessionTarget {
+    /* The conversation kind is part of the key: two conversations on one anchor never share a session (ADR-0072 decision 3). */
+    return { scope: JSON.stringify([this.app.contextPath, userId, this.kind]), anchorType: anchor.anchorType, anchorId: anchor.anchorId, kind: this.kind }
+  }
+
+  private async reloadSessions() {
+    const target = this.controller.state.target
+    if (target) await this.controller.open(target, true)
+  }
+
+  private async newConversation() {
+    if (this.loading || !isAnchor(this.anchor)) return
+    this.showingHistory = false
+    const revision = this.controller.state.revision
+    await this.controller.reset()
+    if (revision !== this.controller.state.revision) this.conversationView++
+  }
+
+  private selectSession(id: string, pickedKind?: string) {
+    this.showingHistory = false
+    const follow = followPickedConversation(pickedKind, this.kind)
+    if (follow) {
+      /* A conversation of another kind on this anchor - the dock follows it rather than refusing it. */
+      this.chosenKind = follow
+      void this.open().then(() => this.controller.select(id) && this.conversationView++)
+      return
+    }
+    const previous = this.sessionId
+    if (this.controller.select(id) && previous !== id) this.conversationView++
+  }
+
+  private onModeChange = (event: CustomEvent) => {
+    const kind = event.detail?.kind
+    if (!kind || kind === this.kind) return
+    this.chosenKind = kind
+    void this.open()
+  }
+
+  /* ── asks from other screens ────────────────────────────────────────────────────── */
+
+  private async takeAsk() {
+    if (!isAnchor(this.anchor) || this.loading) return
+    const ask: AssistantAsk | undefined = takeAssistantAsk()
+    if (!ask) return
+
+    if (!ask.continueCurrent && (ask.name || ask.context || ask.transcript?.length)) {
+      const id = await this.startCarried(ask)
+      if (id) {
+        await this.reloadSessions()
+        this.controller.select(id)
+      }
+    } else if (!ask.continueCurrent) {
+      await this.newConversation()
+    }
+    this.conversationView++
+    this.asking = { ask: ask.ask, draft: ask.draft, requestId: String(Date.now()) }
+  }
+
+  /** A new conversation carrying what the other screen had - its name, a note, earlier turns. */
+  private async startCarried(ask: AssistantAsk): Promise<string | undefined> {
+    const anchor = this.anchor as { anchorType: string; anchorId: string }
+    const created = await client.mutate({
+      mutation: gql`
+        mutation ($t: String!, $i: String!, $n: String) {
+          createAISession(anchorType: $t, anchorId: $i, name: $n) {
+            id
+          }
+        }
+      `,
+      variables: { t: anchor.anchorType, i: anchor.anchorId, n: ask.name || null }
+    })
+    const id = created.data?.createAISession?.id
+    if (!id) return undefined
+    if (ask.context) {
+      await client.mutate({
+        mutation: gql`
+          mutation ($id: String!, $c: String!) {
+            appendSessionNote(sessionId: $id, content: $c)
+          }
+        `,
+        variables: { id, c: ask.context }
+      })
+    }
+    if (ask.transcript?.length) {
+      await client.mutate({
+        mutation: gql`
+          mutation ($id: String!, $turns: JSON!) {
+            appendSessionTurns(sessionId: $id, turns: $turns)
+          }
+        `,
+        variables: { id, turns: ask.transcript.map(turn => ({ role: turn.role === 'ai' ? 'assistant' : 'user', content: turn.content })) }
+      })
+    }
+    return id
+  }
+
+  /* ── proposals ───────────────────────────────────────────────────────────────────── */
+
+  private proposalContext(sessionId?: string): ProposalContext {
+    return {
+      sessionId,
+      surface: this.surface,
+      confirm: async ({ title, text, confirmText, cancelText, type }) =>
+        !!(await OxPrompt.open({
+          type: type ?? 'warning',
+          title,
+          text,
+          confirmButton: { text: confirmText ?? t('confirm', 'OK') },
+          cancelButton: { text: cancelText ?? t('cancel', 'Cancel') }
+        })),
+      notify: (level, message) => notify({ level, message })
+    }
+  }
+
+  private async report(sessionId: string | undefined, proposalKey: string | undefined, outcome: ProposalOutcome) {
+    if (!sessionId || !proposalKey) return
+    try {
+      await client.mutate({
+        mutation: gql`
+          mutation ($id: String!, $key: String!, $outcome: JSON!) {
+            reportProposalOutcome(sessionId: $id, proposalKey: $key, outcome: $outcome)
+          }
+        `,
+        variables: { id: sessionId, key: proposalKey, outcome }
+      })
+    } catch {
+      /* the card then says it heard nothing - never "done" */
+    }
+  }
+
+  /** Every proposal ends in exactly one reported outcome - a kind nobody handles is `unavailable`. */
+  private onProposal = async (event: CustomEvent) => {
+    const { proposal, sessionId, proposalKey } = event.detail ?? {}
+    const outcome = await runProposal(proposal, this.proposalContext(sessionId))
+    if (outcome.verdict === 'unavailable' && outcome.errorCode === 'unknown-proposal-kind') {
+      notify({ level: 'error', message: t('proposal-not-runnable', 'this proposal cannot be run on this screen.') })
+    }
+    await this.report(sessionId, proposalKey, outcome)
+  }
+
+  /* ── board surfaces: the chat's scene edits land on the open board ───────────────── */
+
+  private onScenePatch = async (event: CustomEvent) => {
+    const board = this.surface?.board
+    if (!board) return
+    const result = await board.applyPatch(event.detail)
+    if (result?.missed) notify({ level: 'info', message: t('patch-missed', '{missed} of the changes could not be applied.', { missed: result.missed }) })
+  }
+
+  private onBoardRevert = (event: CustomEvent) => void this.surface?.board?.revertPatch?.(event.detail?.patchId)
+
+  private onSceneAction = (event: CustomEvent) => void this.surface?.board?.applyAction?.(event.detail)
+
+  /* ── drawing ─────────────────────────────────────────────────────────────────────── */
+
+  private stuckLine(): string {
+    if (this.capability === 'not-configured') return t('not-configured', 'no AI is set up for this site. an administrator can set one up in the AI settings.')
+    if (this.capability === 'unknown' && this.asked && !this.loading && !this.failure) return t('capability-unknown', 'whether AI is set up here could not be read.')
+    if (this.capability === 'configured' && !this.surface && !this.loading) return t('no-surface', 'this screen has no conversation.')
+    const anchor = this.anchor
+    if (anchor && !isAnchor(anchor)) return anchor.message
+    return ''
+  }
+
+  private header(): TemplateResult {
+    const surface = this.surface
+    const home = assistantHomeSurface()
+    const ready = this.capability === 'configured' && isAnchor(this.anchor)
+    return html`
+      <div class="scope">
+        <md-icon>${surface?.icon || 'forum'}</md-icon>
+        <span class="what">
+          <span>${surface?.label() || t('title', 'Assistant')}</span>
+          ${surface?.detail ? html`<span class="detail">${surface.detail()}</span>` : nothing}
+        </span>
+        ${home && surface && home !== surface
+          ? html`<button class="sbtn" title=${t('to-home', "back to this application's conversation")} @click=${() => this.useSurface(home)}>
+              <md-icon>home</md-icon>
+            </button>`
+          : nothing}
+        ${ready
+          ? html`<button
+              class="sbtn"
+              title=${this.showingHistory ? t('back-to-conversation', 'back to the conversation') : t('conversations', 'conversations')}
+              @click=${() => (this.showingHistory = !this.showingHistory)}
+            >
+              <md-icon>${this.showingHistory ? 'forum' : 'list'}</md-icon>
+            </button>`
+          : nothing}
+        <button class="sbtn" title=${t('rebind', 'follow this screen again')} @click=${() => this.follow(true)}>
+          <md-icon>refresh</md-icon>
+        </button>
+        <button class="sbtn" title=${t('close', 'close')} @click=${() => closeOverlay(this.viewpart)}>
+          <md-icon>close</md-icon>
+        </button>
+      </div>
+    `
+  }
+
+  /** The home button: talk about the application instead of this screen, until the screen changes. */
+  private useSurface(surface: AssistantSurface) {
+    this.surface = surface
+    this.chosenKind = ''
+    void this.open()
+  }
+
+  render(): TemplateResult {
+    const anchor = this.anchor
+    const ready = this.capability === 'configured' && isAnchor(anchor)
+    const stuck = this.stuckLine()
+    const surface = this.surface
+    const openedFor = this.openedFor
+    const board = surface?.board
+
+    const mode: AssistantMode | undefined = ready ? { kind: this.kind, target: (anchor as any).anchorId, hostContext: {} } : undefined
+
+    return html`
+      ${this.header()}
+      ${ready && this.showingHistory
+        ? html`<ox-assistant-session-manager
+            .anchorType=${(anchor as any).anchorType}
+            .anchorId=${(anchor as any).anchorId}
+            .sessionId=${this.sessionId}
+            .kind=${this.kind}
+            .kindLabels=${this.kindLabels}
+            @assistant-session-select=${(event: CustomEvent) => this.selectSession(event.detail.sessionId, event.detail.kind)}
+            @assistant-session-reset=${() => this.newConversation()}
+            @assistant-session-changed=${() => this.reloadSessions()}
+          ></ox-assistant-session-manager>`
+        : nothing}
+      ${ready && !this.showingHistory
+        ? html`<ox-assistant-session-toolbar
+            .sessions=${this.sessions}
+            .sessionId=${this.sessionId}
+            .loading=${this.loading}
+            .error=${this.failure}
+            historyEnabled
+            @assistant-session-select=${(event: CustomEvent) => this.selectSession(event.detail.sessionId)}
+            @assistant-session-reset=${() => this.newConversation()}
+            @assistant-session-history=${() => (this.showingHistory = true)}
+            @assistant-session-retry=${() => this.open()}
+          ></ox-assistant-session-toolbar>`
+        : nothing}
+      ${ready && !this.showingHistory && !this.loading && !this.failure
+        ? keyed(
+            this.conversationView,
+            html`<ox-assistant-chat
+              .sessionId=${this.sessionId}
+              .prepareSession=${(adopt: (id: string) => void) => this.controller.prepareSession(adopt)}
+              .contextProvider=${() => {
+                /* The screen moved on between writing and sending - do not answer about the old one. */
+                if (openedFor !== this.scopeKey(currentAssistantSurface() ?? surface)) throw new Error(t('screen-changed', 'the screen changed while you were writing. send it again.'))
+                return { hostContext: surface?.hostContext?.() ?? {} }
+              }}
+              .mode=${mode}
+              .subject=${surface?.subject}
+              .chatEndpoint=${board?.chatEndpoint ?? 'assistantChat'}
+              ?board-tools=${!!board}
+              .currentBoard=${board?.currentBoard?.()}
+              .boardProvider=${board?.boardProvider}
+              .selectedRefids=${board?.selectedRefids?.() ?? []}
+              .knownTypes=${board?.knownTypes?.()}
+              .categories=${board?.categories?.()}
+              .componentSchemas=${board?.componentSchemas?.()}
+              .searchProvider=${board?.searchProvider}
+              .autoAsk=${this.asking?.ask}
+              .autoAskRequestId=${this.asking?.requestId}
+              .draft=${this.asking?.draft}
+              .draftRequestId=${this.asking?.requestId}
+              @assistant-mode-change=${this.onModeChange}
+              @assistant-proposal-execute=${this.onProposal}
+              @scene-edit-patch=${this.onScenePatch}
+              @board-edit-revert=${this.onBoardRevert}
+              @scene-action-execute=${this.onSceneAction}
+            ></ox-assistant-chat>`
+          )
+        : nothing}
+      ${stuck
+        ? html`<div class="stuck">
+            ${stuck}
+            ${this.capability === 'unknown'
+              ? html`<div><button class="sbtn" @click=${() => this.open()}><md-icon>refresh</md-icon>${t('retry', 'try again')}</button></div>`
+              : nothing}
+          </div>`
+        : nothing}
+      ${this.failure && !stuck && !ready
+        ? html`<div class="stuck">
+            ${this.failure}
+            <div><button class="sbtn" @click=${() => this.open()}><md-icon>refresh</md-icon>${t('retry', 'try again')}</button></div>
+          </div>`
+        : nothing}
+    `
+  }
+}

package/client/components/assistant-mode.ts

@@ -53,6 +53,8 @@ export interface AssistantModeView {
   examples?: Array<{ label: string; items: string[] }>
   footerNotice?: string
   stagedNotice?: string
+  /** What this conversation accepts as attachments; absent - none (design/ai/shared-dock.md §9-1). */
+  attachments?: { kinds: ('image' | 'text')[]; maxBytes?: number; maxFiles?: number }
 }
 
 /** True when these two describe different conversations, so the old one should be closed. */