@things-factory/ai-assistant 10.1.47 → 10.1.52

package/client/setup-assistant-dock.ts

@@ -0,0 +1,118 @@
+/*
+ * Standing the AI dock up in an application - one call in its bootstrap (design/ai/shared-dock.md §2-1).
+ *
+ *   setupAssistantDock()
+ *   registerAssistantHome({ ... })        // what the app's own conversation is about
+ *   registerSubjectSurface('items', ...)   // how a page's context.subject becomes a surface (if any)
+ *
+ * The dock sits in the aside bar above everything, closed at first; the header band's `forum` button opens
+ * it and carries how many conversations have something unread. Asks from other screens open it too.
+ */
+import '@material/web/icon/icon.js'
+import './components/assistant-dock.js'
+
+import { LitElement, css, html, nothing } from 'lit'
+import { customElement, property, state } from 'lit/decorators.js'
+
+import { i18next } from '@operato/i18n'
+import { appendViewpart, openOverlay, TOOL_POSITION, VIEWPART_LEVEL, VIEWPART_POSITION } from '@operato/layout'
+import { store } from '@operato/shell'
+import { APPEND_APP_TOOL } from '@things-factory/apptool-base/client/index.js'
+
+import { ASSISTANT_DOCK_VIEWPART } from './components/assistant-dock.js'
+import { startSessionActivityFeed, subscribeSessionActivity, unreadSessionCount } from './utils/assistant-activity.js'
+
+@customElement('ox-assistant-dock-button')
+export class AssistantDockButton extends LitElement {
+  static styles = css`
+    :host {
+      position: relative;
+      display: inline-flex;
+      cursor: pointer;
+    }
+
+    .badge {
+      position: absolute;
+      top: -4px;
+      right: -6px;
+      min-width: 14px;
+      height: 14px;
+      padding: 0 3px;
+      box-sizing: border-box;
+      border-radius: 7px;
+      background: var(--md-sys-color-error);
+      color: var(--md-sys-color-on-error);
+      font-size: 9px;
+      line-height: 14px;
+      text-align: center;
+    }
+  `
+
+  @property({ type: String }) viewpart = ASSISTANT_DOCK_VIEWPART
+  @state() private unread = 0
+
+  private unsubscribe?: () => void
+
+  connectedCallback() {
+    super.connectedCallback()
+    this.unread = unreadSessionCount()
+    this.unsubscribe = subscribeSessionActivity(() => (this.unread = unreadSessionCount()))
+  }
+
+  disconnectedCallback() {
+    this.unsubscribe?.()
+    super.disconnectedCallback()
+  }
+
+  /*
+   * Opens, never toggles: after a reload the viewpart can be marked shown while nothing is drawn, and a toggle
+   * then closed it - the first press did nothing (found on :3700, 2026-09-25). The dock's own ✕ closes it.
+   */
+  render() {
+    return html`
+      <md-icon
+        title=${i18next.t('ai-assistant.dock.open', { defaultValue: 'Ask AI' })}
+        @click=${() => openOverlay(this.viewpart, { backdrop: false })}
+        >forum</md-icon
+      >
+      ${this.unread ? html`<span class="badge">${this.unread}</span>` : nothing}
+    `
+  }
+}
+
+let installed = false
+
+export function setupAssistantDock(options: { viewpart?: string } = {}): void {
+  if (installed) return
+  installed = true
+  const viewpart = options.viewpart ?? ASSISTANT_DOCK_VIEWPART
+
+  startSessionActivityFeed()
+
+  appendViewpart({
+    name: viewpart,
+    /*
+     * `persistent` keeps the dock on editors that bleed wide (the board modeller hides the aside bar with
+     * `widebleed`) - those are the screens where the conversation authors, so the dock must still open there.
+     */
+    viewpart: {
+      show: false,
+      persistent: true,
+      level: VIEWPART_LEVEL.TOPMOST,
+      template: html`<ox-assistant-dock .viewpart=${viewpart}></ox-assistant-dock>`
+    },
+    position: VIEWPART_POSITION.ASIDEBAR
+  })
+
+  store.dispatch({
+    type: APPEND_APP_TOOL,
+    tool: {
+      name: 'assistant-dock-open',
+      position: TOOL_POSITION.REAR,
+      template: html`<ox-assistant-dock-button .viewpart=${viewpart}></ox-assistant-dock-button>`
+    }
+  })
+
+  /* askAssistant() from any screen opens the dock. */
+  window.addEventListener('assistant-dock-open', () => openOverlay(viewpart, { backdrop: false }))
+}

package/client/utils/assistant-activity.ts

@@ -0,0 +1,122 @@
+/*
+ * AI 세션 활동 구독 — **앱 전역 1회**. 도크가 닫혀 있어도(마운트되지 않아도) 새 소식을 안다.
+ *
+ * operato-twin 의 `twin-ai-activity.ts` 에서 올려 왔다(2026-09-25, design/ai/shared-dock.md §2-8) — 안 읽음은
+ * 모든 앱에서 같은 기능이다. `setupAssistantDock()` 이 부팅에서 한 번 연다.
+ *
+ * ── 왜 도크가 아니라 여기인가 ───────────────────────────────────────────────
+ * 도크는 asidebar viewpart 이고 닫혀 있으면 **렌더되지 않는다**(템플릿이 아예 안 붙는다). 그래서
+ * 도크 안에서 구독하면 닫아 둔 동안 아무 소식을 받지 못한다 — 배지를 띄울 수 없다.
+ * 구독은 부팅 시 한 번 열고, 도크·컨텍스트 밴드는 이 스토어를 본다.
+ *
+ * ── 종류에 따라 다르게 다룬다 ───────────────────────────────────────────────
+ *   message — 새 메시지. 안 읽은 세션으로 표시(배지 올림). **내가 보낸 것은 올리지 않는다.**
+ *   meta    — 이름 변경 등. 목록 갱신만 알리고 배지는 올리지 않는다(소음 방지).
+ *
+ * 정확한 미읽음 **개수**는 세지 않는다 — 세션 수만 센다(서버 목록 정책과 같다).
+ */
+import gql from 'graphql-tag'
+
+import { client, gqlContext } from '@operato/graphql'
+
+
+export interface SessionActivity {
+  sessionId: string
+  kind: 'message' | 'meta'
+  anchorType?: string
+  anchorId?: string
+  at: string
+  preview?: string
+  actorId?: string
+}
+
+type Listener = (activity: SessionActivity) => void
+
+const listeners = new Set<Listener>()
+/** 안 읽은 세션 id — 개수가 아니라 세션 단위. 도크에서 그 세션을 열면 지운다. */
+const unreadSessions = new Set<string>()
+let subscription: { unsubscribe(): void } | null = null
+
+const ACTIVITY_SUBSCRIPTION = gql`
+  subscription MySessionActivity {
+    mySessionActivity {
+      sessionId
+      kind
+      anchorType
+      anchorId
+      at
+      preview
+      actorId
+    }
+  }
+`
+
+
+export function unreadSessionCount(): number {
+  return unreadSessions.size
+}
+
+export function isSessionUnread(sessionId: string): boolean {
+  return unreadSessions.has(sessionId)
+}
+
+/** 그 세션을 읽었다 — 도크가 세션을 열 때 호출(서버 markSessionRead 와 짝). */
+export function clearSessionUnread(sessionId: string): void {
+  if (unreadSessions.delete(sessionId)) notify({ sessionId, kind: 'meta', at: new Date().toISOString() })
+}
+
+export function subscribeSessionActivity(fn: Listener): () => void {
+  listeners.add(fn)
+  return () => listeners.delete(fn)
+}
+
+function notify(activity: SessionActivity) {
+  listeners.forEach(fn => {
+    try {
+      fn(activity)
+    } catch {
+      /* 구독자 오류가 다른 구독자를 막지 않는다 */
+    }
+  })
+}
+
+/**
+ * 구독 시작 — 부팅에서 1회. 재호출은 무시(중복 구독 방지).
+ * 실패해도 앱을 막지 않는다 — 배지가 없을 뿐이고, 도크를 열면 목록을 직접 읽는다.
+ */
+export function startSessionActivityFeed(): void {
+  if (subscription) return
+  try {
+    subscription = client
+      .subscribe({ query: ACTIVITY_SUBSCRIPTION, context: gqlContext() })
+      .subscribe({
+        next: ({ data }: any) => {
+          const activity: SessionActivity | undefined = data?.mySessionActivity
+          if (!activity?.sessionId) return
+          /* 자기 발신은 배지를 올리지 않는다 — 방금 내가 쓴 것이 안 읽음으로 뜨면 어색하다.
+           * 서버는 actorId(사용자 id)를 싣지만 클라는 내부 관리키를 판정에 쓰지 않는다 →
+           * 자기 발신 판정은 도크가 열려 있는 세션인지로 대신한다(그 세션은 이미 읽고 있다). */
+          if (activity.kind === 'message' && !isOpenSession(activity.sessionId)) {
+            unreadSessions.add(activity.sessionId)
+          }
+          notify(activity)
+        },
+        error: () => {
+          subscription = null // 재연결은 다음 호출에 맡긴다(자동 재시도 루프를 두지 않는다)
+        }
+      })
+  } catch {
+    subscription = null
+  }
+}
+
+/* 도크가 지금 열어 둔 세션 — 그 세션의 활동은 배지를 올리지 않는다(보고 있으므로). */
+let openSessionId = ''
+export function setOpenSession(sessionId: string): void {
+  openSessionId = sessionId || ''
+  if (openSessionId) clearSessionUnread(openSessionId)
+}
+function isOpenSession(sessionId: string): boolean {
+  return !!openSessionId && openSessionId === sessionId
+}
+

package/client/utils/assistant-ask.ts

@@ -0,0 +1,44 @@
+/*
+ * Asking the assistant from another screen - `askAssistant()` (design/ai/shared-dock.md §2-11).
+ *
+ * Generalised from operato-twin's promotion channel and operato-plant's ask box: a toast's "ask AI", a
+ * header ask box, a performance page carrying its context. The request waits here until the dock takes it,
+ * so a dock that is closed (not mounted) still gets it when it opens.
+ */
+export interface AssistantAsk {
+  /** Sent as the next question. */
+  ask?: string
+  /** Put in the input, not sent. */
+  draft?: string
+  /** Ask in the open conversation instead of a new one. */
+  continueCurrent?: boolean
+  /** A new conversation's name. */
+  name?: string
+  /** Turns carried into the new conversation before the question. */
+  transcript?: { role: 'user' | 'ai'; content: string }[]
+  /** A note stored first: what the screen was showing when the person asked. */
+  context?: string
+}
+
+type Listener = () => void
+
+let pending: AssistantAsk | undefined
+const listeners = new Set<Listener>()
+
+export function askAssistant(ask: AssistantAsk): void {
+  pending = ask
+  listeners.forEach(listener => listener())
+  window.dispatchEvent(new CustomEvent('assistant-dock-open'))
+}
+
+/** The dock takes the request once. */
+export function takeAssistantAsk(): AssistantAsk | undefined {
+  const ask = pending
+  pending = undefined
+  return ask
+}
+
+export function subscribeAssistantAsk(listener: Listener): () => void {
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}

package/client/utils/assistant-proposals.ts

@@ -0,0 +1,50 @@
+/*
+ * Proposal handlers - each proposal kind is applied by the package that declared its tool
+ * (design/ai/shared-dock.md §4). The dock has no kind-specific code: it finds the handler, runs it,
+ * and reports the outcome on every branch (ADR-0070). A kind nobody handles is `unavailable`.
+ */
+import type { AssistantSurface } from './assistant-surface.js'
+
+export type ProposalVerdict = 'accepted' | 'refused' | 'unavailable' | 'declined'
+
+export interface ProposalOutcome {
+  verdict: ProposalVerdict
+  errorCode?: string
+  applied?: number
+  missed?: number
+  /** A line for the conversation, besides the outcome itself (e.g. what was created). */
+  note?: string
+}
+
+export interface ProposalContext {
+  sessionId?: string
+  surface?: AssistantSurface
+  /** Asks the person before anything irreversible. `false` → the handler returns `declined`. */
+  confirm(options: { title: string; text: string; confirmText?: string; cancelText?: string; type?: 'warning' | 'info' }): Promise<boolean>
+  notify(level: 'info' | 'error', message: string): void
+}
+
+export type ProposalHandler = (proposal: any, context: ProposalContext) => Promise<ProposalOutcome>
+
+const handlers = new Map<string, ProposalHandler>()
+
+/** Registered by the package that declares the tool - `proposeAction` by twin, a figure candidate by figure-ui. */
+export function registerProposalHandler(tool: string, handler: ProposalHandler): void {
+  handlers.set(tool, handler)
+}
+
+export function proposalHandlerOf(tool: string | undefined): ProposalHandler | undefined {
+  return tool ? handlers.get(tool) : undefined
+}
+
+/** Runs the proposal - never throws; a failure is a `refused` outcome with its message as the code. */
+export async function runProposal(proposal: any, context: ProposalContext): Promise<ProposalOutcome> {
+  const handler = proposalHandlerOf(proposal?.tool)
+  if (!handler) return { verdict: 'unavailable', errorCode: 'unknown-proposal-kind' }
+  try {
+    const outcome = await handler(proposal, context)
+    return outcome?.verdict ? outcome : { verdict: 'unavailable', errorCode: 'no-outcome' }
+  } catch (error) {
+    return { verdict: 'refused', errorCode: (error as Error)?.message || 'failed' }
+  }
+}

package/client/utils/assistant-session-actions.ts

@@ -0,0 +1,18 @@
+/*
+ * Which actions a row of the conversation list offers this viewer - pure, so the rule is tested alone.
+ *
+ * The same hints the server gives on each inbox entry; the doors decide again:
+ *   rename        any participant                 (the name is the topic label; reversible)
+ *   hide/unhide   anyone, for their own list only (reversible)
+ *   delete        the creator (`mine`)            (not reversible from a screen)
+ *   visibility    the owner (`owner`)             (opening shows what is already written)
+ */
+export function sessionActions(entry: { participant?: boolean; hidden?: boolean; mine?: boolean; owner?: boolean }) {
+  return {
+    rename: entry.participant !== false,
+    hide: !entry.hidden,
+    unhide: !!entry.hidden,
+    remove: !!entry.mine,
+    setVisibility: !!entry.owner
+  }
+}

package/client/utils/assistant-session-admin.ts

@@ -0,0 +1,167 @@
+import { client } from '@operato/graphql'
+import { i18next } from '@operato/i18n'
+import gql from 'graphql-tag'
+
+export { sessionActions } from './assistant-session-actions.js'
+
+/**
+ * Managing the conversations on one anchor - list, rename, hide, delete, and who may read them.
+ *
+ * These were written once, inside operato-twin's dock (things-factory `b3d1081f4c`, `b44c986c07`,
+ * 2026-07-30), and every other dock (plant, figure, warehouse, ecs) had only the tabs. They are the
+ * framework's doors (`chatSessionInbox` · `renameAISession` · `hideAISession` · `deleteAISession` ·
+ * `setSessionVisibility`), so the screen for them belongs here too - one list every dock opens.
+ *
+ * Who may do what is the server's to decide; the entry carries hints only:
+ *   rename        any participant                 (the name is the topic label; reversible)
+ *   hide/unhide   anyone, for their own list only (reversible)
+ *   delete        the creator (`mine`)            (not reversible from a screen)
+ *   visibility    the owner (`owner`)             (opening shows what is already written)
+ */
+
+export type SessionVisibility = 'open' | 'private'
+
+/** One row of `chatSessionInbox`, as the list draws it. */
+export interface AssistantSessionEntry {
+  id: string
+  name?: string
+  kind?: string
+  lastMessageAt?: string
+  lastMessagePreview?: string
+  previewRedacted?: boolean
+  unread?: boolean
+  participant?: boolean
+  /** I created it - only then may I delete it. */
+  mine?: boolean
+  /** I own it - only then may I change who reads it. */
+  owner?: boolean
+  /** Hidden from my own list (returned only with the hidden filter on). */
+  hidden?: boolean
+  visibility?: SessionVisibility | string
+}
+
+/** Legacy single filter - kept for callers written before the filter set. */
+export type AssistantSessionFilter = 'all' | 'mine' | 'hidden'
+
+/** What the manager narrows by (design/ai/shared-dock.md §2-6). Defaults: this kind, everyone's, any visibility, hidden out. */
+export interface AssistantSessionFilters {
+  /** A kind (mode) to list; empty lists every kind on the anchor. */
+  kind?: string
+  whose?: 'all' | 'mine' | 'participant'
+  visibility?: 'all' | 'open' | 'private'
+  includeHidden?: boolean
+  unreadOnly?: boolean
+}
+
+export interface AssistantSessionQuery {
+  anchorType: string
+  anchorId: string
+  search?: string
+  filter?: AssistantSessionFilter
+  filters?: AssistantSessionFilters
+  limit?: number
+  offset?: number
+}
+
+export interface AssistantSessionPage {
+  entries: AssistantSessionEntry[]
+  /** How many pass the filter - so "load more" knows whether the end of the list is the end of the data. */
+  total: number
+  /** How many I hid - so a hidden conversation is never forgotten. */
+  hiddenCount: number
+}
+
+export interface AssistantSessionAdmin {
+  inbox(query: AssistantSessionQuery): Promise<AssistantSessionPage>
+  rename(sessionId: string, name: string): Promise<boolean>
+  hide(sessionId: string, hidden: boolean): Promise<boolean>
+  remove(sessionId: string): Promise<boolean>
+  setVisibility(sessionId: string, visibility: SessionVisibility): Promise<boolean>
+}
+
+/** The page size the server allows at most (`chatSessionInbox` clamps to 200). */
+export const SESSION_PAGE_MAX = 200
+
+async function mutate(mutation: any, variables: Record<string, unknown>, field: string): Promise<boolean> {
+  const result = await client.mutate({ mutation, variables })
+  if (result.errors?.length) throw new Error(result.errors[0].message)
+  return result.data?.[field] === true
+}
+
+/** The framework's session doors, as they are. */
+export const assistantSessionAdmin: AssistantSessionAdmin = {
+  async inbox({ anchorType, anchorId, search, filter = 'all', filters = {}, limit = 50, offset = 0 }) {
+    const hidden = filters.includeHidden ?? filter === 'hidden'
+    const mine = filters.whose ? filters.whose === 'mine' : filter === 'mine'
+    const result = await client.query({
+      query: gql`
+        query ($t: String!, $i: String!, $h: Boolean, $q: String, $m: Boolean, $l: Int, $o: Int, $k: String, $p: Boolean, $v: String, $u: Boolean) {
+          hiddenSessionCount(anchorType: $t, anchorId: $i)
+          chatSessionInboxTotal(anchorType: $t, anchorId: $i, showHidden: $h, search: $q, mineOnly: $m, kind: $k, participantOnly: $p, visibility: $v, unreadOnly: $u)
+          chatSessionInbox(anchorType: $t, anchorId: $i, showHidden: $h, search: $q, mineOnly: $m, kind: $k, participantOnly: $p, visibility: $v, unreadOnly: $u, limit: $l, offset: $o) {
+            id
+            name
+            kind
+            lastMessageAt
+            lastMessagePreview
+            previewRedacted
+            unread
+            participant
+            mine
+            owner
+            hidden
+            visibility
+          }
+        }
+      `,
+      variables: {
+        t: anchorType,
+        i: anchorId,
+        /* Hidden ones only when asked - elsewhere they stay out of the list. */
+        h: hidden,
+        q: search?.trim() || null,
+        m: mine,
+        k: filters.kind || null,
+        p: filters.whose === 'participant' || null,
+        v: filters.visibility && filters.visibility !== 'all' ? filters.visibility : null,
+        u: filters.unreadOnly || null,
+        l: Math.min(SESSION_PAGE_MAX, Math.max(1, limit)),
+        o: Math.max(0, offset)
+      },
+      fetchPolicy: 'no-cache'
+    })
+
+    if (result.errors?.length) throw new Error(result.errors[0].message)
+    const entries = result.data?.chatSessionInbox
+    if (!Array.isArray(entries)) {
+      throw new Error(i18next.t('ai-assistant.text.sessions-unreadable', { defaultValue: 'could not load the conversation list.' }))
+    }
+
+    return {
+      /* With the hidden filter the server returns hidden ones alongside the rest, marked - the total counts both. */
+      entries,
+      total: result.data?.chatSessionInboxTotal ?? entries.length,
+      hiddenCount: result.data?.hiddenSessionCount ?? 0
+    }
+  },
+
+  rename(sessionId, name) {
+    return mutate(gql`mutation ($id: String!, $n: String!) { renameAISession(sessionId: $id, name: $n) }`, { id: sessionId, n: name }, 'renameAISession')
+  },
+
+  hide(sessionId, hidden) {
+    return mutate(gql`mutation ($id: String!, $h: Boolean) { hideAISession(sessionId: $id, hidden: $h) }`, { id: sessionId, h: hidden }, 'hideAISession')
+  },
+
+  remove(sessionId) {
+    return mutate(gql`mutation ($id: String!) { deleteAISession(sessionId: $id) }`, { id: sessionId }, 'deleteAISession')
+  },
+
+  setVisibility(sessionId, visibility) {
+    return mutate(
+      gql`mutation ($id: String!, $v: String!) { setSessionVisibility(sessionId: $id, visibility: $v) }`,
+      { id: sessionId, v: visibility },
+      'setSessionVisibility'
+    )
+  }
+}

package/client/utils/assistant-session-controller.ts

@@ -17,6 +17,8 @@ export interface AssistantSessionTarget {
   scope: string
   anchorType: string
   anchorId: string
+  /** The conversation kind (mode) the tabs list - all readable conversations of it, not only mine (shared dock §2-6). */
+  kind?: string
 }
 export interface AssistantSessionTransport {
   list(target: AssistantSessionTarget): Promise<AssistantSession[]>

package/client/utils/assistant-session-transport.ts

@@ -16,8 +16,12 @@ export const assistantSessionTransport: AssistantSessionTransport = {
   },
   async list(target) {
     const result = await client.query({
-      query: gql`query($type:String!,$id:String!){chatSessionInbox(anchorType:$type,anchorId:$id,mineOnly:true,limit:100){id name kind}}`,
-      variables: { type: target.anchorType, id: target.anchorId }, fetchPolicy: 'no-cache'
+      /*
+       * Every readable conversation of this kind on the anchor, not only mine - the same scope the manager
+       * shows by default (design/ai/shared-dock.md §2-6). Without a kind: every kind, as before.
+       */
+      query: gql`query($type:String!,$id:String!,$kind:String){chatSessionInbox(anchorType:$type,anchorId:$id,kind:$kind,limit:100){id name kind}}`,
+      variables: { type: target.anchorType, id: target.anchorId, kind: target.kind || null }, fetchPolicy: 'no-cache'
     })
     if (result.errors?.length) throw new Error(result.errors[0].message)
     if (!Array.isArray(result.data?.chatSessionInbox)) throw new Error(i18next.t('ai-assistant.text.sessions-unreadable', { defaultValue: 'could not load the conversation list.' }))