@things-factory/ai-assistant 10.1.210 → 10.1.213

package/client/components/assistant-chat.ts

@@ -3,6 +3,8 @@ import { rosterName } from './roster-identity'
 import { notify } from '@operato/layout'
 import './assistant-invite.js'
 import { TypingRoom } from '../utils/assistant-typing.js'
+import { isInviteProposal, personLine, type InvitePerson } from '../utils/invite-proposal.js'
+import { noteForDisplay } from '../utils/assistant-selection.js'
 /**
  * <ox-assistant-chat> — AI 도우미 채팅 컴포넌트 (Lit).
  *
@@ -79,6 +81,7 @@ import './entry-review.js'
 import { entryGroupOf, entryReadyCount, entryTitle, isChangeProposal, isEntryProposal, latestEntryKeys } from '../utils/entry-proposal.js'
 import { isWorkspaceProposal, versionOfCard, workspaceAddress } from '../utils/workspace.js'
 import { isOpenPageProposal, openPageNote } from '../utils/open-page.js'
+import { proposalViewOf } from '../utils/assistant-proposals.js'
 
 interface ChatLine {
   role: 'user' | 'assistant' | 'system'
@@ -380,6 +383,12 @@ const CHAT_TYPING_SUBSCRIPTION = gql`
     }
   }
 `
+/* The selection a screen request carries, noted before the request (design/ai/shared-dock.md §2-11-1). */
+const APPEND_SESSION_NOTE_MUTATION = gql`
+  mutation AppendSessionNote($sessionId: String!, $content: String!) {
+    appendSessionNote(sessionId: $sessionId, content: $content)
+  }
+`
 const TOUCH_PRESENCE_MUTATION = gql`
   mutation TouchPresence($sessionId: String!) {
     touchPresence(sessionId: $sessionId)
@@ -968,6 +977,41 @@ export class OxAssistantChat extends LitElement {
     this.attachments = draft.attachments
   }
 
+  /**
+   * A request made on the screen (「AI와 작업」, design/ai/shared-dock.md §2-11-1) - in this conversation, made now if it
+   * has none yet: the selection's note first, then the request, sent at once. What the person was writing is set aside
+   * while it goes and put back after, whatever happened. Says whether it was sent and, if not, why.
+   */
+  async sendScreenRequest(text: string, note: string): Promise<{ sent: boolean; reason?: string }> {
+    if (this.busy) return { sent: false, reason: i18next.t('ai-assistant.text.screen-request-busy', { defaultValue: 'an answer is still being written.' }) }
+    const kept = this.takeDraft()
+    try {
+      if (!this.sessionId && this.prepareSession) {
+        await this.prepareSession(id => {
+          this.adoptingSession = true
+          this.sessionId = id
+        })
+        await this.updateComplete
+      }
+      if (!this.sessionId) return { sent: false, reason: i18next.t('ai-assistant.text.screen-request-no-session', { defaultValue: 'this screen has no conversation to send to.' }) }
+      if (note) {
+        const noted = await client.mutate({ mutation: APPEND_SESSION_NOTE_MUTATION, variables: { sessionId: this.sessionId, content: note } })
+        if (noted.errors?.length) throw new Error(noted.errors[0].message)
+        await this.loadHistory()
+      }
+      this.errorMessage = undefined
+      this.input = text
+      await this.send()
+      return this.errorMessage ? { sent: false, reason: this.errorMessage } : { sent: true }
+    } catch (error) {
+      return { sent: false, reason: error instanceof Error ? error.message : String(error) }
+    } finally {
+      /* The request is the screen's - it never stays in the box; the box gets back what the person had written. */
+      if (this.input.trim() === text.trim()) this.input = ''
+      if (kept && !this.input.trim() && !this.attachments.length) this.restoreDraft(kept)
+    }
+  }
+
   @state()
   private errorMessage?: string
 
@@ -2029,6 +2073,16 @@ export class OxAssistantChat extends LitElement {
       --md-icon-size: 13px;
       color: inherit;
     }
+    /* The invite card's people - where each works, quieter than the name; a picked card greys every button. */
+    .proposal-choices .choice-chip .invite-where {
+      margin-left: 4px;
+      opacity: 0.7;
+      font-size: 0.92em;
+    }
+    .proposal-choices .choice-chip:disabled {
+      opacity: 0.5;
+      cursor: default;
+    }
 
     /* The entry card's way to the large review - a quiet action under its table, never a second run button. */
     .workspace-review {
@@ -3285,7 +3339,7 @@ export class OxAssistantChat extends LitElement {
                           class="sys-text"
                           title=${i18next.t('ai-assistant.text.toggle-system-note', { defaultValue: 'click to expand' })}
                           @click=${() => this.toggleSystemNote(idx)}
-                          >${content}</span
+                          >${noteForDisplay(content)}</span
                         >`
                       : content}
                 ${line.attachments && line.attachments.length > 0
@@ -4468,7 +4522,11 @@ export class OxAssistantChat extends LitElement {
           /* A screen card opens the application's list with the question's conditions; it runs nothing (design/ai/read-targets.md §5). */
           if (isOpenPageProposal(p)) return this.renderOpenPageCard(p)
           const card = proposalCardState(key, { outcomes, requested, sentHere: this.sentProposals.has(key) })
+          /* An invite card: one person, one button; several of one name, one button each - the person picks (ADR-0073 decision 3). */
+          if (isInviteProposal(p)) return this.renderInviteCard(p, key, card.state)
           const entry = isEntryProposal(p)
+          /* A package's own card - its preview under the line, its words on the button (assistant-proposals.ts ProposalView). */
+          const view = entry ? undefined : proposalViewOf(p.tool)
           const replaced = entry && latestEntry?.get(entryGroupOf(p)) !== key && card.state === 'ready'
           const ready = entry ? entryReadyCount(p) : 0
           const sent = card.state !== 'ready' || replaced || (entry && ready === 0)
@@ -4515,7 +4573,9 @@ export class OxAssistantChat extends LitElement {
                                 ? i18next.t('ai-assistant.entry.change', { defaultValue: 'change {count} records', count: ready })
                                 : i18next.t('ai-assistant.entry.enter', { defaultValue: 'enter {count} rows', count: ready })
                               : i18next.t('ai-assistant.entry.nothing-to-enter', { defaultValue: 'nothing to enter' })
-                            : i18next.t('ai-assistant.button.run-proposal', { defaultValue: 'run' })}
+                            : view?.runLabelKey || view?.runLabel
+                              ? i18next.t(view.runLabelKey ?? '', { defaultValue: view.runLabel ?? 'run' })
+                              : i18next.t('ai-assistant.button.run-proposal', { defaultValue: 'run' })}
                     </button>
                   `}
               ${/*
@@ -4532,6 +4592,7 @@ export class OxAssistantChat extends LitElement {
               ` : nothing}
             </div>
             ${entry ? html`<ox-assistant-entry-review .proposal=${p}></ox-assistant-entry-review>` : nothing}
+            ${view?.previewTag ? this.renderProposalPreview(view.previewTag, p, key) : nothing}
             ${entry && this.sessionId && offersWorkspaceReview(p)
               ? html`<button
                   class="workspace-review"
@@ -4561,6 +4622,58 @@ export class OxAssistantChat extends LitElement {
     `
   }
 
+  /** A package's preview under its card - the element is the package's; it is handed the proposal and where it is. */
+  private renderProposalPreview(tag: string, p: any, key: string) {
+    const element = (this.proposalPreviews.get(key) as any) ?? document.createElement(tag)
+    this.proposalPreviews.set(key, element)
+    element.proposal = p
+    element.sessionId = this.sessionId
+    element.proposalKey = key
+    return html`${element}`
+  }
+
+  /** One preview element per card, kept across renders so it does not read again on every keystroke. */
+  private proposalPreviews = new Map<string, HTMLElement>()
+
+  /**
+   * The invite card. Pressing it is the person's act - the dock calls the invite door with their request. With several
+   * people of one name each is a button with where they work; the press carries whom they picked.
+   */
+  private renderInviteCard(p: any, key: string, state: string) {
+    const people: InvitePerson[] = p.people
+    const sent = state !== 'ready'
+    const status = sent ? this.proposalStateText(key) : ''
+    return html`
+      <div class="proposal invite ${sent ? 'sent' : ''}">
+        <md-icon>${p.icon || 'person_add'}</md-icon>
+        <span class="pbody">
+          <span class="plabel">${p.label}</span>
+          ${p.reason ? html`<span class="preason">${p.reason}</span>` : nothing}
+          ${sent && people.length > 1 ? html`<span class="preason">${status}</span>` : nothing}
+        </span>
+        ${people.length === 1
+          ? html`<button class="run" ?disabled=${sent} @click=${() => this.executeProposal(p, key)}>
+              ${sent ? status : i18next.t('ai-assistant.button.invite', { defaultValue: 'Invite' })}
+            </button>`
+          : nothing}
+      </div>
+      ${people.length > 1
+        ? html`<div class="proposal-choices invite-people" role="group" aria-label=${p.label}>
+            ${people.map(
+              person => html`<button
+                class="choice-chip"
+                ?disabled=${sent}
+                title=${personLine(person)}
+                @click=${() => this.executeProposal({ ...p, chosen: person.userId }, key)}>
+                <md-icon>person_add</md-icon>
+                <span>${person.name}${personLine(person) ? html` <span class="invite-where">${personLine(person)}</span>` : nothing}</span>
+              </button>`
+            )}
+          </div>`
+        : nothing}
+    `
+  }
+
   /** The screen card - which list, the conditions the screen does not take, and the way to open it. */
   private renderOpenPageCard(p: any) {
     const note = openPageNote(p, (key, options) => String(i18next.t(key, options)))

package/client/components/assistant-dock.ts

@@ -31,8 +31,11 @@ import {
   type AssistantSurface
 } from '../utils/assistant-surface.js'
 import { runProposal, setEntryProposalHandler, type ProposalContext, type ProposalOutcome } from '../utils/assistant-proposals.js'
+/* The invite card's handler - ai-assistant's own tool, registered by its own module (design/ai/shared-dock.md §4). */
+import '../utils/invite-proposal-register.js'
 import { entryProposalHandler, type EntryApplyAnswer } from '../utils/entry-proposal.js'
-import { holdAssistantAsk, subscribeAssistantAsk, takeAssistantAsk, type AssistantAsk } from '../utils/assistant-ask.js'
+import { holdAssistantAsk, peekAssistantAsk, settleAssistantAsk, subscribeAssistantAsk, takeAssistantAsk, type AssistantAsk } from '../utils/assistant-ask.js'
+import { selectionNote } from '../utils/assistant-selection.js'
 import { surfaceTransition } from '../utils/assistant-navigation.js'
 
 export const ASSISTANT_DOCK_VIEWPART = 'assistant-dock'
@@ -381,6 +384,7 @@ export class AssistantDock extends localize(i18next)(LitElement) {
     this.removeEventListener('assistant-start-new-session', this.onStartNewSession)
     this.removeEventListener('assistant-open-page', this.onOpenPage as EventListener)
     this.unsubscribers.splice(0).forEach(unsubscribe => unsubscribe())
+    clearTimeout(this.takeTimer)
     setOpenSession('')
     super.disconnectedCallback()
   }
@@ -442,7 +446,11 @@ export class AssistantDock extends localize(i18next)(LitElement) {
     if (transition === 'reset') {
       this.asking = undefined
       this.capability = 'unknown'
-      if (this.openedIdentity) takeAssistantAsk()
+      if (this.openedIdentity) {
+        const dropped = takeAssistantAsk()
+        /* Another account or domain - the request was not this one's to send; the screen is told. */
+        if (dropped) settleAssistantAsk(dropped, { sent: false, reason: 'identity-changed' })
+      }
     }
     this.surface = next
     void this.open()
@@ -557,7 +565,18 @@ export class AssistantDock extends localize(i18next)(LitElement) {
 
   private async takeAsk() {
     if (this.loading || !this.anchor) return
-    if (this.navigationState.busy || this.navigationState.draft) {
+    /* A request made on the screen with what was picked there (「AI와 작업」) has rules of its own (§2-11-1). */
+    if (peekAssistantAsk()?.selection) return this.takeScreenRequest()
+    /*
+     * A request the person made on this screen is never dropped for what the dock is doing (2026-10-24: 「AI와 작업」
+     * pressed again was thrown away because the input still held the first press's draft). An answer being written
+     * finishes first, then the request is taken. Unsent words are asked about - the person keeps writing or lets them go.
+     */
+    if (this.navigationState.busy) {
+      this.takeWhenIdle()
+      return
+    }
+    if (this.navigationState.draft && !(await this.mayLeaveConversation())) {
       const waiting = takeAssistantAsk()
       if (waiting) notify({ level: 'info', message: t('ask-kept-current', 'The current conversation was kept. Switch to the intended subject before asking again.') })
       return
@@ -594,6 +613,90 @@ export class AssistantDock extends localize(i18next)(LitElement) {
     this.asking = { ask: ask.ask, draft: ask.draft, requestId: String(Date.now()) }
   }
 
+  private takeTimer?: ReturnType<typeof setTimeout>
+
+  /**
+   * This person's own conversation on this screen - the most recent they sit in; none, a new one made on sending. What
+   * they were writing comes along.
+   */
+  private async goToOwnConversation() {
+    const kept = (this.renderRoot.querySelector('ox-assistant-chat') as any)?.takeDraft?.()
+    const own = this.sessions.find(one => one.participant !== false && one.id !== this.sessionId)
+    const revision = this.controller.state.revision
+    if (own) {
+      if (this.controller.select(own.id)) this.conversationView++
+    } else {
+      await this.controller.reset()
+      if (revision !== this.controller.state.revision) this.conversationView++
+    }
+    await this.updateComplete
+    if (kept) (this.renderRoot.querySelector('ox-assistant-chat') as any)?.restoreDraft?.(kept)
+  }
+
+  /*
+   * ── A screen request (「AI와 작업」) - design/ai/shared-dock.md §2-11-1 ─────────────────────────────────────────
+   * The user (2026-10-24): 「"AI와 작업" 기능이 unstable 하다. 작동 방식을 신뢰할 수 있도록 새로운 세션을 여는지, 기존 세션을
+   * 활용하는지 등등을 명확하게 하라.」 One way, every time:
+   *   1. this screen's conversation - the one the dock opens for this screen; none yet, one is made on sending. The dock
+   *      showing another screen's conversation, or its list, comes back here. Never a new conversation per press.
+   *   2. the selection at the press is noted for that turn - a line the person reads, the ids for the model; a later
+   *      press's note replaces it (SELECTION_RULE).
+   *   3. the request is sent, always - never left as a draft.
+   *   4. what the person was writing in the box is set aside while the request goes, and put back.
+   *   5. not sent: said in a notice, and the screen is told so it keeps the request on its bar.
+   *   6. an answer being written: said, and the request goes right after it - never dropped.
+   */
+  private waitingNoticeFor?: AssistantAsk
+
+  private async takeScreenRequest() {
+    const waiting = peekAssistantAsk()
+    if (!waiting?.selection) return
+    if (this.navigationState.busy) {
+      if (this.waitingNoticeFor !== waiting) {
+        this.waitingNoticeFor = waiting
+        notify({ level: 'info', message: t('screen-request-waits', 'An answer is being written - your request goes right after it.') })
+      }
+      this.takeWhenIdle()
+      return
+    }
+    const here = currentAssistantSurface()
+    if (this.scopeKey(here) !== this.openedFor || this.openedIdentity !== this.identityKey()) {
+      /* Another screen's conversation is open - back to this screen's; open() takes the request again when it stands. */
+      this.keepDraft()
+      this.surface = here
+      await this.open()
+      return
+    }
+    const ask = takeAssistantAsk()!
+    this.waitingNoticeFor = undefined
+    const fail = (reason: string) => {
+      notify({ level: 'error', message: reason })
+      settleAssistantAsk(ask, { sent: false, reason })
+    }
+    if (!isAnchor(this.anchor)) return fail(this.anchor?.message || t('no-conversation', 'there is no conversation for this screen.'))
+    this.showingHistory = false
+    /*
+     * The dock opens the first conversation it can read when this person has none here yet - someone else's open one,
+     * found 2026-10-24: the request went into Admin's public 「회사가치를 제시해보라」. A screen request is the person's own
+     * work: a conversation they do not sit in is not this screen's conversation for them. Their own on this screen is
+     * used - the most recent one; none yet, one is started (made on sending).
+     */
+    if (this.sessions.find(one => one.id === this.sessionId)?.participant === false) await this.goToOwnConversation()
+    await this.updateComplete
+    const chat = this.renderRoot.querySelector('ox-assistant-chat') as any
+    if (!chat?.sendScreenRequest) return fail(t('screen-request-not-ready', 'The conversation is not ready yet. Try again in a moment.'))
+    const request = ask.ask?.trim() || t('screen-request-default', 'Read the selected records and suggest what can be done with them now.')
+    const outcome = await chat.sendScreenRequest(request, selectionNote(ask.selection!, t))
+    if (!outcome?.sent) return fail(outcome?.reason || t('screen-request-failed', 'The request was not sent. Try again.'))
+    settleAssistantAsk(ask, { sent: true })
+  }
+
+  /** The request waits (it is still pending) while an answer is written, then is taken. */
+  private takeWhenIdle() {
+    clearTimeout(this.takeTimer)
+    this.takeTimer = setTimeout(() => (this.navigationState.busy ? this.takeWhenIdle() : void this.takeAsk()), 300)
+  }
+
   /** 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 }

package/client/components/workspace-view.ts

@@ -26,6 +26,29 @@ const t = (key: string, defaultValue: string, options: Record<string, unknown> =
 const shown = (value: unknown) =>
   value === null || value === undefined ? '' : typeof value === 'number' ? value.toLocaleString(i18next.language || undefined) : String(value)
 
+/*
+ * A label cut to the width it has, at the axis size: a wide (Hangul, CJK) character about 11 units, any other about 6.5.
+ * The whole label is its title - 「CJ올리브네트웍스」 under a narrow bar ran into the next one (2026-10-24).
+ */
+const charWidth = (char: string) => (/[\u1100-\u11ff\u2e80-\u9fff\uac00-\ud7af\uff00-\uffef]/.test(char) ? 11 : 6.5)
+const fitted = (label: string, width: number) => {
+  const room = width * 0.92
+  let used = 0
+  const chars = [...label]
+  for (let i = 0; i < chars.length; i++) {
+    used += charWidth(chars[i])
+    if (used > room) return `${chars.slice(0, Math.max(1, i - 1)).join('')}…`
+  }
+  return label
+}
+
+/*
+ * An axis step in the reader's short form - 300,000,000 is 「3억」 in Korean and 「300M」 in English - so the axis fits its
+ * margin; a mark's own title keeps the whole number. Below ten thousand the number is written whole.
+ */
+const tickShown = (value: number) =>
+  Math.abs(value) < 10_000 ? shown(value) : new Intl.NumberFormat(i18next.language || undefined, { notation: 'compact', maximumFractionDigits: 1 }).format(value)
+
 /** Four round steps from zero to above the largest value. */
 function ticksFor(max: number): number[] {
   if (!(max > 0)) return [0, 1]
@@ -246,10 +269,40 @@ export class AssistantWorkspaceView extends LitElement {
     .markdown :first-child {
       margin-top: 0;
     }
+
+    /*
+     * One block in a small frame - a dashboard card (ADR-0160 decision 5). No outer margin, a figure sized to be read
+     * across a room, and a table that fills the frame and scrolls inside it.
+     */
+    :host([compact]) section {
+      margin: 0;
+    }
+
+    :host([compact]) .metrics {
+      grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+    }
+
+    :host([compact]) .metric {
+      border: 0;
+      padding: 4px 0;
+      background: transparent;
+    }
+
+    :host([compact]) .metric .value {
+      font-size: 30px;
+      line-height: 1.2;
+      letter-spacing: -0.01em;
+    }
+
+    :host([compact]) .scroll {
+      max-height: var(--assistant-workspace-table-max-height, 320px);
+    }
   `
   ]
 
   @property({ attribute: false }) workspace?: WorkspaceView
+  /** One block in a small frame - a dashboard card: no outer margin, a large figure, a lower chart. */
+  @property({ type: Boolean, reflect: true }) compact = false
 
   @state() private sorts: Record<number, { column: string; direction: 'asc' | 'desc' }> = {}
   @state() private asTable = new Set<number>()
@@ -373,7 +426,7 @@ export class AssistantWorkspaceView extends LitElement {
     }
 
     const W = 640
-    const H = 240
+    const H = this.compact ? 200 : 240
     const left = 56
     const bottom = 28
     const plotW = W - left - 8
@@ -411,9 +464,9 @@ export class AssistantWorkspaceView extends LitElement {
     return html`<section class="chart" role="img" aria-label=${block.caption || series.map(name).join(', ')}>
       ${bar}
       <svg viewBox="0 0 ${W} ${H}">
-        ${ticks.map(tick => svg`<line class="grid" x1=${left} x2=${W - 8} y1=${y(tick)} y2=${y(tick)}></line><text class="tick" x=${left - 6} y=${y(tick) + 4} text-anchor="end">${shown(tick)}</text>`)}
+        ${ticks.map(tick => svg`<line class="grid" x1=${left} x2=${W - 8} y1=${y(tick)} y2=${y(tick)}></line><text class="tick" x=${left - 6} y=${y(tick) + 4} text-anchor="end">${tickShown(tick)}</text>`)}
         ${marks}
-        ${x.map((label, j) => (j % everyNth ? nothing : svg`<text class="tick" x=${left + band * (j + 0.5)} y=${H - 8} text-anchor="middle">${label}</text>`))}
+        ${x.map((label, j) => (j % everyNth ? nothing : svg`<text class="tick" x=${left + band * (j + 0.5)} y=${H - 8} text-anchor="middle"><title>${label}</title>${fitted(label, band * everyNth)}</text>`))}
       </svg>
       ${series.length > 1
         ? html`<div class="legend">${series.map((one, s) => html`<span><span class="swatch" style="background:${colours[s % 8]}"></span>${name(one)}</span>`)}</div>`

package/client/index.ts

@@ -20,7 +20,10 @@ export * from './components/assistant-dock.js'
 export * from './setup-assistant-dock.js'
 export * from './utils/assistant-surface.js'
 export * from './utils/assistant-proposals.js'
+/* The AI 작업판's blocks, drawn - also a dashboard card's (ADR-0160 decision 5). */
+export * from './components/workspace-view.js'
 export * from './utils/assistant-ask.js'
+export * from './utils/assistant-selection.js'
 export * from './utils/assistant-activity.js'
 export * from './utils/assistant-request-context.js'
 export * from './utils/assistant-capability.js'

package/client/utils/assistant-ask.test.ts

@@ -0,0 +1,38 @@
+/*
+ * What becomes of a request a screen hands the dock - the screen waits on the answer and keeps the person's words
+ * unless it was sent (design/ai/shared-dock.md §2-11-1, rule 5).
+ */
+import { askAssistant, peekAssistantAsk, settleAssistantAsk, takeAssistantAsk } from './assistant-ask'
+
+beforeAll(() => {
+  ;(globalThis as any).window = (globalThis as any).window ?? { dispatchEvent: () => true }
+  ;(globalThis as any).CustomEvent = (globalThis as any).CustomEvent ?? class { constructor(public type: string) {} }
+})
+afterEach(() => takeAssistantAsk())
+
+describe('a request and its outcome', () => {
+  it('★ the screen hears whether it was sent, and why not', async () => {
+    const ask = { ask: 'read them', selection: { title: 'L', records: [{ id: 'a' }] } }
+    const outcome = askAssistant(ask)
+    expect(peekAssistantAsk()).toBe(ask)
+    settleAssistantAsk(takeAssistantAsk()!, { sent: false, reason: 'not ready' })
+    expect(await outcome).toEqual({ sent: false, reason: 'not ready' })
+  })
+
+  it('peeking leaves it waiting; it is settled once', async () => {
+    const ask = { ask: 'x' }
+    const outcome = askAssistant(ask)
+    expect(peekAssistantAsk()).toBe(ask)
+    expect(peekAssistantAsk()).toBe(ask)
+    settleAssistantAsk(ask, { sent: true })
+    settleAssistantAsk(ask, { sent: false, reason: 'late' })
+    expect(await outcome).toEqual({ sent: true })
+  })
+
+  it('a request replaced before the dock took it is told it was not sent', async () => {
+    const first = askAssistant({ ask: 'first' })
+    askAssistant({ ask: 'second' })
+    expect(await first).toEqual({ sent: false, reason: 'replaced' })
+    expect(peekAssistantAsk()?.ask).toBe('second')
+  })
+})

package/client/utils/assistant-ask.ts

@@ -5,6 +5,7 @@
  * 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.
  */
+import type { AssistantSelection } from './assistant-selection.js'
 export interface AssistantAsk {
   /** Sent as the next question. */
   ask?: string
@@ -18,17 +19,50 @@ export interface AssistantAsk {
   transcript?: { role: 'user' | 'ai'; content: string }[]
   /** A note stored first: what the screen was showing when the person asked. */
   context?: string
+  /**
+   * The records the person picked on the screen - a screen request (「AI와 작업」, design/ai/shared-dock.md §2-11-1). It
+   * goes to this screen's conversation, never a new one; the selection is noted for that turn (a line the person reads,
+   * the ids for the model - assistant-selection.ts) and `ask` is sent at once.
+   */
+  selection?: AssistantSelection
+}
+
+/** What became of a request - a screen keeps what the person wrote when it was not sent, and says nothing twice. */
+export interface AssistantAskOutcome {
+  sent: boolean
+  /** Why it was not sent, in the person's words - the dock has already said it. */
+  reason?: string
 }
 
 type Listener = () => void
 
 let pending: AssistantAsk | undefined
 const listeners = new Set<Listener>()
+const settlers = new WeakMap<AssistantAsk, (outcome: AssistantAskOutcome) => void>()
 
-export function askAssistant(ask: AssistantAsk): void {
+/**
+ * Hands the request to the dock. The promise says what became of it once the dock has dealt with it - sent, or not and
+ * why. A request replaced before the dock took it is not sent, and says so.
+ */
+export function askAssistant(ask: AssistantAsk): Promise<AssistantAskOutcome> {
+  if (pending && pending !== ask) settleAssistantAsk(pending, { sent: false, reason: 'replaced' })
+  const outcome = new Promise<AssistantAskOutcome>(resolve => settlers.set(ask, resolve))
   pending = ask
   listeners.forEach(listener => listener())
   window.dispatchEvent(new CustomEvent('assistant-dock-open'))
+  return outcome
+}
+
+/** The dock tells the screen what became of its request. Once; later calls do nothing. */
+export function settleAssistantAsk(ask: AssistantAsk, outcome: AssistantAskOutcome): void {
+  const settle = settlers.get(ask)
+  settlers.delete(ask)
+  settle?.(outcome)
+}
+
+/** The waiting request, left waiting - the dock decides how to take it before taking it. */
+export function peekAssistantAsk(): AssistantAsk | undefined {
+  return pending
 }
 
 /**

package/client/utils/assistant-proposals.ts

@@ -37,6 +37,29 @@ export function proposalHandlerOf(tool: string | undefined): ProposalHandler | u
   return tool ? handlers.get(tool) : undefined
 }
 
+/**
+ * How a package's card is drawn in the conversation, besides the framework's line: an element drawn under it (given
+ * `proposal`, `sessionId` and `proposalKey`), and the words of its button. A dashboard card draws its preview as the
+ * one looking at the conversation (ADR-0160 decision 6). Registered by the package that declares the tool.
+ */
+export interface ProposalView {
+  /** A custom element's tag name - defined by the registering package. */
+  previewTag?: string
+  /** i18n key of the button, and its words when the key has none. */
+  runLabelKey?: string
+  runLabel?: string
+}
+
+const views = new Map<string, ProposalView>()
+
+export function registerProposalView(tool: string, view: ProposalView): void {
+  views.set(tool, view)
+}
+
+export function proposalViewOf(tool: string | undefined): ProposalView | undefined {
+  return tool ? views.get(tool) : undefined
+}
+
 /*
  * Data entry cards are the framework's, whatever record they enter (design/ai/data-entry.md §5): one
  * handler asks the server to enter the stored rows. The dock sets it; no app registers one per record.

package/client/utils/assistant-selection.test.ts

@@ -0,0 +1,30 @@
+import { noteForDisplay, selectionNote, SELECTION_KEYS_PREFIX } from './assistant-selection'
+
+const t = (_key: string, defaultValue: string, options: any = {}) => defaultValue.replace(/\{(\w+)\}/g, (_, name) => String(options[name]))
+const contract = (id: string, label: string) => ({ id, label })
+
+describe('the records picked on a screen, as a note', () => {
+  it('★ the person reads a line of names; the model reads the list and the ids', () => {
+    const note = selectionNote({ title: '계약 대장', list: 'contracts', records: [contract('c-1', 'H2022019 · 브라이스톤 IT3.0 Website')] }, t)
+    expect(note).toBe(`Selected 1 · 계약 대장: H2022019 · 브라이스톤 IT3.0 Website\n${SELECTION_KEYS_PREFIX} contracts c-1`)
+    expect(note).not.toMatch(/[{}"]|explicit-page-selection/)
+  })
+
+  it('★ the screen draws the person\'s line only', () => {
+    const note = selectionNote({ title: '계약 대장', list: 'contracts', records: [contract('c-1', 'H2022019')] }, t)
+    expect(noteForDisplay(note)).toBe('Selected 1 · 계약 대장: H2022019')
+    expect(noteForDisplay('a plain note\nsecond line')).toBe('a plain note\nsecond line')
+  })
+
+  it('every id reaches the model; the names are cut after a few, the rest counted', () => {
+    const records = Array.from({ length: 7 }, (_, i) => contract(`c-${i}`, `C${i}`))
+    const note = selectionNote({ title: 'L', records }, t)
+    expect(note.split('\n')[0]).toBe('Selected 7 · L: C0, C1, C2, C3, C4 and 2 more')
+    expect(note.split('\n')[1]).toBe(`${SELECTION_KEYS_PREFIX} ${records.map(one => one.id).join(' ')}`)
+  })
+
+  it('a record picked twice is one; nothing picked is no note', () => {
+    expect(selectionNote({ title: 'L', records: [contract('a', 'A'), contract('a', 'A')] }, t)).toBe(`Selected 1 · L: A\n${SELECTION_KEYS_PREFIX} a`)
+    expect(selectionNote({ title: 'L', records: [] }, t)).toBe('')
+  })
+})

package/client/utils/assistant-selection.ts

@@ -0,0 +1,47 @@
+/*
+ * The records a person picked on a screen and handed to the assistant - `askAssistant({ selection })`.
+ *
+ * The conversation keeps them as a note: one line the person reads (「선택 1건 · 계약 대장: H2022019 · 브라이스톤 IT3.0
+ * Website」) and one line the model reads - the list and the ids, after `[keys]`. The screen hides the key line; the
+ * model is handed the note as stored. Until 2026-10-24 the screen sent the selection as JSON and the conversation
+ * opened on `{"source":"explicit-page-selection",…}`.
+ */
+
+/** The line the model reads begins with this; the conversation does not draw it. */
+export const SELECTION_KEYS_PREFIX = '[keys]'
+
+/** Labels named on the person's line - the rest are counted. */
+export const SELECTION_LABELS_SHOWN = 5
+
+export interface AssistantSelection {
+  /** The list the records were picked from, as the person knows it (「계약 대장」). */
+  title: string
+  /** The list's query (`contracts`) - which list the ids belong to, for the model. */
+  list?: string
+  records: { id: string; label?: string }[]
+}
+
+export type SelectionTranslate = (key: string, defaultValue: string, options?: Record<string, unknown>) => string
+
+/** The note stored in the conversation - the person's line, then the key line. Empty when nothing was picked. */
+export function selectionNote(selection: AssistantSelection, t: SelectionTranslate): string {
+  const seen = new Set<string>()
+  const records = (selection?.records ?? []).filter(one => one?.id && !seen.has(one.id) && !!seen.add(one.id))
+  if (!records.length) return ''
+  const labels = records.map(one => (one.label || '').replace(/\s+/g, ' ').trim()).filter(Boolean)
+  const shown = labels.slice(0, SELECTION_LABELS_SHOWN).join(', ')
+  const rest = labels.length - Math.min(labels.length, SELECTION_LABELS_SHOWN)
+  const line = t('selection-note', 'Selected {count} · {title}', { count: records.length, title: selection.title })
+  const named = shown ? `${line}: ${shown}${rest > 0 ? ` ${t('selection-more', 'and {count} more', { count: rest })}` : ''}` : line
+  const keys = `${SELECTION_KEYS_PREFIX} ${selection.list ? `${selection.list} ` : ''}${records.map(one => one.id).join(' ')}`
+  return `${named}\n${keys}`
+}
+
+/** A note as the conversation draws it - without the line only the model reads. */
+export function noteForDisplay(content: string): string {
+  return (content ?? '')
+    .split('\n')
+    .filter(line => !line.startsWith(SELECTION_KEYS_PREFIX))
+    .join('\n')
+    .trim()
+}

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

@@ -13,6 +13,8 @@ export interface AssistantSession {
   kind?: string
   /** Who reads it: 'open' (everyone in the domain), 'group' (the people the owner brought in) or 'private' (the owner alone). The dock draws an open one apart. */
   visibility?: string
+  /** Whether this person sits in it - `false` for someone else's open conversation the dock showed; absent on one just made. */
+  participant?: boolean
 }
 export interface AssistantSessionTarget {
   /** Account/domain boundary supplied by the authenticated host. */