@things-factory/ai-assistant 10.1.210 → 10.1.213

package/server/service/people/invite-tools.ts

@@ -0,0 +1,159 @@
+/*
+ * proposeInvite - the model offers a card that brings someone into this conversation (ADR-0073 decision 3).
+ *
+ * The card is a proposal: the model seats nobody. What an assistant writes must not seat people (mention-invite.ts,
+ * rule ①), so the seat is given when a person presses the card - the dock calls `inviteToAISession` with that
+ * person's request, and the door asks `maySeat` with their seat. This tool only finds who is meant and says whether
+ * this person could press it here.
+ *
+ * Who is meant is the server's to settle, never the model's memory: the name is looked up in the organization's own
+ * list as the person (the read people-read.ts opens), so a user id the model made up is never on a card. One person
+ * by that name - the card invites them. Several - the card lists each and the person picks one; the model does not ask.
+ */
+import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
+import { getRepository } from '@things-factory/shell'
+
+import { runAsCaller } from '../data-entry/entry-tools.js'
+import type { GraphqlRunner } from '../data-entry/entry-update.js'
+import { ChatSession } from '../chat-session/chat-session.js'
+import { maySeat } from '../chat-session/session-visibility.js'
+import { ChatSessionParticipant } from '../chat-session-participant/chat-session-participant.js'
+import { isRoomRole } from '../chat-session-participant/participant-lookup-roles.js'
+import { PEOPLE_SELECTION } from './people-read.js'
+import { INVITE_CATEGORY } from './people-keys.js'
+
+/** At most this many people on one card - a name that matches more is too broad to pick from. */
+export const MAX_INVITE_CANDIDATES = 8
+
+export interface InviteCandidate {
+  userId: string
+  name: string
+  department?: string
+  position?: string
+}
+
+const PEOPLE_QUERY =
+  'query ($filters: [Filter!], $pagination: Pagination, $search: String) ' +
+  `{ employees(filters: $filters, pagination: $pagination, search: $search) { items { ${PEOPLE_SELECTION} } total } }`
+
+const ACTIVE = { name: 'active', operator: 'eq', value: true }
+
+const candidateOf = (row: any): InviteCandidate | undefined =>
+  row?.user?.id
+    ? {
+        userId: String(row.user.id),
+        name: String(row.name ?? ''),
+        ...(row.department?.name ? { department: String(row.department.name) } : {}),
+        ...(row.jobPosition ? { position: String(row.jobPosition) } : {})
+      }
+    : undefined
+
+/**
+ * The people a name means, as the person may see them: the exact name first, then the name as a search term. Only
+ * people with an account - an invite seats a user.
+ */
+export async function findPeopleNamed(run: GraphqlRunner, name: string): Promise<{ people: InviteCandidate[]; error?: string }> {
+  const ask = async (variables: Record<string, unknown>) => {
+    const answer = await run(PEOPLE_QUERY, { pagination: { page: 1, limit: MAX_INVITE_CANDIDATES + 1 }, ...variables })
+    if (answer.errors?.length) return { error: answer.errors.map(one => one.message).join('; ') }
+    return { rows: (answer.data?.employees?.items ?? []) as any[] }
+  }
+  const exact = await ask({ filters: [ACTIVE, { name: 'name', operator: 'eq', value: name }] })
+  if ('error' in exact) return { people: [], error: exact.error }
+  const rows = exact.rows!.length ? exact.rows! : ((await ask({ filters: [ACTIVE], search: name })) as any).rows ?? []
+  return { people: rows.map(candidateOf).filter(Boolean) as InviteCandidate[] }
+}
+
+/** Why this person cannot bring anyone into this room, in their words - or nothing when they can. */
+function seatRefusal(visibility: string | null | undefined, t: (key: string, options: any) => string): string | undefined {
+  if (visibility === 'private')
+    return t('ai-assistant.text.invite-private-refused', { defaultValue: 'a private conversation is yours alone. make it a group to bring people in.' })
+  return t('ai-assistant.text.invite-owner-only', { defaultValue: 'only the person who started this group conversation can bring people in.' })
+}
+
+export async function proposeInvite(args: any, context: any, run: GraphqlRunner = runAsCaller(context)) {
+  const t = (key: string, options: any) => (typeof context?.t === 'function' ? context.t(key, options) : String(options?.defaultValue ?? key))
+  const { domain, user } = context?.state ?? {}
+  const name = typeof args?.name === 'string' ? args.name.trim() : ''
+  const wanted = typeof args?.userId === 'string' ? args.userId.trim() : ''
+  if (!name) return { rejected: true, error: 'no-name', message: 'say whom to invite - the name the person used.' }
+
+  const conversationId = context?.conversation?.id
+  const session: any = conversationId && domain?.id ? await getRepository(ChatSession).findOne({ where: { id: conversationId, domain: { id: domain.id } } as any }) : undefined
+  if (!session) return { rejected: true, error: 'no-conversation', message: 'this conversation is not stored yet, so nobody can be brought into it.' }
+
+  /* Asked before anyone is looked up: the card must be one this person can press here. */
+  const seats = await getRepository(ChatSessionParticipant).find({ where: { domain: { id: domain.id }, session: { id: session.id } } as any })
+  const mine = seats.find((seat: any) => seat.userId === user?.id)?.role
+  if (!maySeat(session.visibility, mine)) {
+    /* Who reads the conversation is the person's to change, in the conversation list - the model has no tool for it (2026-10-24: it offered 「그룹 대화로 바꿔줘」). */
+    return {
+      rejected: true,
+      error: 'may-not-invite',
+      message: `${seatRefusal(session.visibility, t)} Say so in one line - do not offer a card. Who reads this conversation is changed by the person who started it, from the conversation list (⋯); you cannot change it, so never offer to or suggest asking you.`
+    }
+  }
+
+  const found = await findPeopleNamed(run, name)
+  if (found.error) return { rejected: true, error: 'people-unreadable', message: `the people list could not be read: ${found.error}` }
+  const here = new Set(seats.filter((seat: any) => isRoomRole(seat.role)).map((seat: any) => seat.userId))
+  const already = found.people.filter(one => here.has(one.userId))
+  let people = found.people.filter(one => !here.has(one.userId) && one.userId !== user?.id)
+  if (wanted) people = people.filter(one => one.userId === wanted)
+
+  if (!people.length) {
+    return already.length
+      ? { rejected: true, error: 'already-here', message: `${already.map(one => one.name).join(', ')} is already in this conversation.` }
+      : { rejected: true, error: 'not-found', message: `no one named "${name}" with an account is in the people list this person may see.` }
+  }
+  if (people.length > MAX_INVITE_CANDIDATES) {
+    return { rejected: true, error: 'too-many', message: `more than ${MAX_INVITE_CANDIDATES} people match "${name}" - ask for the full name or the department.` }
+  }
+
+  const one = people.length === 1 ? people[0] : undefined
+  return {
+    proposed: true,
+    kind: 'invite',
+    icon: 'person_add',
+    label: one
+      ? t('ai-assistant.people.invite-one', { name: one.name, defaultValue: 'Invite {name} to this conversation' })
+      : t('ai-assistant.people.invite-pick', { name, count: people.length, defaultValue: '{count} people named {name} - pick whom to invite' }),
+    ...(one && (one.department || one.position) ? { reason: [one.department, one.position].filter(Boolean).join(' · ') } : {}),
+    people,
+    message: one
+      ? `the card invites ${one.name}${one.department ? ` (${one.department})` : ''}. The person presses it; they are told when they join. Say that in one line.`
+      : `${people.length} people match "${name}"; the card lists each with department and position and the person picks one. Do not ask which - the card does.`
+  }
+}
+
+const spec = {
+  kind: 'read',
+  name: 'proposeInvite',
+  /* It reads people through the organization's list - the same door that list has, so it is offered where that list is. */
+  doors: ['Query.employees'],
+  description:
+    'Offer a card that brings someone into this conversation. Give the name the person used; the server finds them in ' +
+    "the organization's people list and puts them on the card (several people by that name: the card lists each, the " +
+    'person picks). The person presses the card - nobody joins until then. One call per person.',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: 'The name of the person to invite, as the person said it.' },
+      userId: { type: 'string', description: 'The user id from the people list, when it was read already and the person meant that one.' }
+    },
+    required: ['name']
+  },
+  builder: (args: any, context: any) => proposeInvite(args, context)
+} as ToolSpec
+
+export const inviteCategory: ToolCategory = {
+  name: INVITE_CATEGORY,
+  description: 'bring someone into this conversation - a card the person presses',
+  guidance: [
+    '- When the person asks to invite, add or bring someone into this conversation, call proposeInvite with that name in the same turn. Never send them to a screen to do it.',
+    '- To answer who someone is or who works where, read the people list (queryOrganizationEmployee).'
+  ].join('\n'),
+  specs: [spec]
+}
+
+registerToolCategory(inviteCategory)

package/server/service/people/invite.test.ts

@@ -0,0 +1,159 @@
+/*
+ * The invite card (people/invite-tools.ts) on sqlite - the room's rules are the stored ones, the people list is a
+ * stand-in for the organization's query as the person.
+ *
+ * Asked 「정연희 초대해 줘」 the model said it had no tool to look people up and sent the person to a screen
+ * (2026-10-24). Now the name is found in the people list and the card carries whom it means; the card itself seats
+ * nobody - a person pressing it does, through the invite door.
+ */
+import type { DataSource } from 'typeorm'
+
+const { DataSource: TypeOrmDataSource } = require('typeorm')
+const shell = require('@things-factory/shell')
+const authBase = require('@things-factory/auth-base')
+
+function loadCompiled(modulePath: string): any {
+  const { existsSync } = require('fs')
+  const { join } = require('path')
+  const resolved = join(__dirname, '..', '..', '..', 'dist-server', 'service', `${modulePath}.js`)
+  if (!existsSync(resolved)) throw new Error(`ai-assistant has no build output: ${resolved}\nBuild first:\n  yarn workspace @things-factory/ai-assistant build:server`)
+  return require(resolved)
+}
+const { ChatSession } = loadCompiled('chat-session/chat-session')
+const { ChatMessage } = loadCompiled('chat-message/chat-message')
+const { ChatSessionParticipant } = loadCompiled('chat-session-participant/chat-session-participant')
+const { proposeInvite, MAX_INVITE_CANDIDATES } = loadCompiled('people/invite-tools')
+
+let db: DataSource
+let domain: any
+let owner: any
+let member: any
+let session: any
+let asked: Array<{ document: string; variables: any }>
+
+beforeAll(async () => {
+  db = new TypeOrmDataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    dropSchema: true,
+    namingStrategy: new shell.NamingStrategy(),
+    entities: [...shell.entities, ...authBase.entities, ChatSession, ChatMessage, ChatSessionParticipant],
+    logging: false
+  })
+  await db.initialize()
+  shell.addDataSource('default', db)
+  domain = await db.getRepository(shell.Domain).save({ name: 'acme', subdomain: 'acme' })
+  owner = await db.getRepository(authBase.User).save({ name: 'owner', username: 'owner', email: 'owner@example.com', status: 'activated' })
+  member = await db.getRepository(authBase.User).save({ name: 'member', username: 'member', email: 'member@example.com', status: 'activated' })
+})
+
+afterAll(async () => {
+  shell.removeDataSource('default')
+  await db?.destroy()
+})
+
+beforeEach(async () => {
+  asked = []
+  session = await db.getRepository(ChatSession).save({ domain, anchorType: 'domain', anchorId: domain.id, name: 'pricing', visibility: 'group', creator: owner })
+  await db.getRepository(ChatSessionParticipant).save({ domain, session: { id: session.id }, user: { id: owner.id }, role: 'owner' })
+  await db.getRepository(ChatSessionParticipant).save({ domain, session: { id: session.id }, user: { id: member.id }, role: 'member' })
+})
+
+const person = (name: string, userId: string | null, department = 'Sales', position = 'Manager') => ({
+  id: `e-${name}-${userId}`,
+  name,
+  jobPosition: position,
+  department: { id: `d-${department}`, name: department },
+  user: userId ? { id: userId } : null
+})
+
+/** The people list as the organization's query answers it: by exact name, then by search. */
+function peopleList(rows: any[]) {
+  return async (document: string, variables: any) => {
+    asked.push({ document, variables })
+    const exact = (variables.filters ?? []).find((one: any) => one.name === 'name')
+    const items = exact ? rows.filter(row => row.name === exact.value) : rows.filter(row => row.name.includes(variables.search ?? ''))
+    return { data: { employees: { items, total: items.length } } }
+  }
+}
+
+const as = (user: any, conversation: any = session) => ({ state: { domain, user }, ...(conversation ? { conversation: { id: conversation.id } } : {}) })
+const seats = async () => (await db.getRepository(ChatSessionParticipant).find({ where: { session: { id: session.id } } as any })).map((row: any) => [row.userId, row.role]).sort()
+
+describe('the invite card', () => {
+  it('★ one person by that name - the card invites them, with where they work', async () => {
+    const card = await proposeInvite({ name: '정연희' }, as(owner), peopleList([person('정연희', 'u-jung'), person('김민수', 'u-kim')]))
+    expect(card).toMatchObject({ proposed: true, kind: 'invite', people: [{ userId: 'u-jung', name: '정연희', department: 'Sales', position: 'Manager' }], reason: 'Sales · Manager' })
+  })
+
+  it('★ the card seats nobody - only a person pressing it does (the invite door)', async () => {
+    const before = await seats()
+    await proposeInvite({ name: '정연희' }, as(owner), peopleList([person('정연희', 'u-jung')]))
+    expect(await seats()).toEqual(before)
+  })
+
+  it('★ two people of one name - the card lists both and the person picks', async () => {
+    const card = await proposeInvite({ name: '정연희' }, as(owner), peopleList([person('정연희', 'u-1', 'Sales'), person('정연희', 'u-2', 'Finance')]))
+    expect(card.people.map((one: any) => one.userId)).toEqual(['u-1', 'u-2'])
+    expect(card.reason).toBeUndefined()
+    expect(card.message).toMatch(/do not ask which/i)
+  })
+
+  it('a user id read before narrows the card to that one', async () => {
+    const card = await proposeInvite({ name: '정연희', userId: 'u-2' }, as(owner), peopleList([person('정연희', 'u-1'), person('정연희', 'u-2')]))
+    expect(card.people.map((one: any) => one.userId)).toEqual(['u-2'])
+  })
+
+  it('★ a user id the model made up is never on a card', async () => {
+    const card = await proposeInvite({ name: '정연희', userId: 'made-up' }, as(owner), peopleList([person('정연희', 'u-1')]))
+    expect(card).toMatchObject({ rejected: true, error: 'not-found' })
+  })
+
+  it('no exact name - the name is searched', async () => {
+    const card = await proposeInvite({ name: '연희' }, as(owner), peopleList([person('정연희', 'u-1')]))
+    expect(card.people.map((one: any) => one.userId)).toEqual(['u-1'])
+    expect(asked[1].variables.search).toBe('연희')
+  })
+
+  it('people who left are never asked for, and no contact or bank field is read', async () => {
+    await proposeInvite({ name: '정연희' }, as(owner), peopleList([person('정연희', 'u-1')]))
+    expect(asked[0].variables.filters).toContainEqual({ name: 'active', operator: 'eq', value: true })
+    expect(asked[0].document).not.toMatch(/phone|email|address|bank|emergency|contact|photo/i)
+  })
+
+  it('someone without an account cannot be invited; someone already here is said', async () => {
+    expect(await proposeInvite({ name: '정연희' }, as(owner), peopleList([person('정연희', null)]))).toMatchObject({ rejected: true, error: 'not-found' })
+    expect(await proposeInvite({ name: 'member' }, as(owner), peopleList([person('member', member.id)]))).toMatchObject({ rejected: true, error: 'already-here' })
+  })
+
+  it('a name that matches too many is narrowed first', async () => {
+    const many = Array.from({ length: MAX_INVITE_CANDIDATES + 1 }, (_, i) => person('정연희', `u-${i}`))
+    expect(await proposeInvite({ name: '정연희' }, as(owner), peopleList(many))).toMatchObject({ rejected: true, error: 'too-many' })
+  })
+})
+
+describe('the card is offered only where the person could press it', () => {
+  it('★ a member of a group cannot bring anyone in - no card, and nobody is looked up', async () => {
+    const card = await proposeInvite({ name: '정연희' }, as(member), peopleList([person('정연희', 'u-1')]))
+    expect(card).toMatchObject({ rejected: true, error: 'may-not-invite' })
+    expect(card.message).toMatch(/you cannot change it, so never offer/)
+    expect(asked).toEqual([])
+  })
+
+  it('★ a private conversation takes nobody', async () => {
+    await db.getRepository(ChatSession).update(session.id, { visibility: 'private' })
+    expect(await proposeInvite({ name: '정연희' }, as(owner), peopleList([person('정연희', 'u-1')]))).toMatchObject({ rejected: true, error: 'may-not-invite' })
+  })
+
+  it('in an open conversation anyone may point a colleague at it', async () => {
+    await db.getRepository(ChatSession).update(session.id, { visibility: 'open' })
+    expect(await proposeInvite({ name: '정연희' }, as(member), peopleList([person('정연희', 'u-1')]))).toMatchObject({ proposed: true })
+  })
+
+  it('a turn without a stored conversation, or one of another domain, has no room to invite into', async () => {
+    expect(await proposeInvite({ name: '정연희' }, as(owner, null), peopleList([]))).toMatchObject({ rejected: true, error: 'no-conversation' })
+    const other = await db.getRepository(shell.Domain).save({ name: 'other', subdomain: 'other' })
+    expect(await proposeInvite({ name: '정연희' }, { state: { domain: other, user: owner }, conversation: { id: session.id } }, peopleList([]))).toMatchObject({ rejected: true, error: 'no-conversation' })
+  })
+})

package/server/service/people/people-keys.ts

@@ -0,0 +1,16 @@
+/*
+ * The names of the people tools - every conversation carries them (mode-categories.ts), so they live apart from the
+ * tools themselves and the categories can be named without loading them.
+ */
+
+/** The organization's people as a read target - its `employees` list, read as the person (people-read.ts). */
+export const PEOPLE_READ_KEY = 'organization.employee'
+
+/** The category of that read - `data-read:<key>`, as every read target's. */
+export const PEOPLE_READ_CATEGORY = `data-read:${PEOPLE_READ_KEY}`
+
+/** The invite card - bring someone into this conversation (invite-tools.ts). */
+export const INVITE_CATEGORY = 'chat-invite'
+
+/** Both, in the order a turn puts them in front: find the person, then the card. */
+export const PEOPLE_CATEGORIES = [PEOPLE_READ_CATEGORY, INVITE_CATEGORY]

package/server/service/people/people-read.test.ts

@@ -0,0 +1,82 @@
+/*
+ * The people list every conversation reads (people-read.ts) - the organization's own query, behind its own door, and
+ * nothing private in what it reads.
+ */
+import { peopleReadTarget, PEOPLE_SELECTION } from './people-read'
+import { PEOPLE_CATEGORIES, PEOPLE_READ_CATEGORY, INVITE_CATEGORY } from './people-keys'
+import { modeFrontCategories, modeToolCategories, unattendedToolCategories } from '../assistant-mode/mode-categories'
+import { rootFieldOf } from '../data-entry/entry-target'
+
+describe('the people list', () => {
+  const target = peopleReadTarget()
+
+  it("★ reads the organization's own list - its door decides who may read people", () => {
+    expect(rootFieldOf(target.query, 'query')).toBe('Query.employees')
+    expect(target.key).toBe('organization.employee')
+  })
+
+  it('★ the invite card reads people through the same door - offered only where the list is', () => {
+    /* The tool module holds entities - read as built, as the database suites do. */
+    const { inviteCategory } = require(require('path').join(__dirname, '..', '..', '..', 'dist-server', 'service', 'people', 'invite-tools.js'))
+    expect(inviteCategory.specs.map((spec: any) => spec.doors)).toEqual([[rootFieldOf(target.query, 'query')]])
+  })
+
+  it('★ reads no contact, address, bank or emergency field', () => {
+    expect(target.query).not.toMatch(/phone|email|address|bank|emergency|contact|photo|profile|note/i)
+    expect(PEOPLE_SELECTION.split(/[\s{}]+/).filter(Boolean).sort()).toEqual(['alias', 'department', 'id', 'id', 'id', 'jobPosition', 'jobResponsibility', 'name', 'name', 'user'].sort())
+  })
+
+  it('people who left are out of reach - a fixed filter the model cannot lift', () => {
+    expect(target.fixedFilters).toEqual([{ name: 'active', operator: 'eq', value: true }])
+  })
+
+  it('★ a department, a position, a responsibility each has its own condition - never the name search', () => {
+    const by = (name: string) => target.criteria.find(one => one.name === name)!
+    expect(by('position').filter('프로')).toEqual({ name: 'jobPosition', operator: 'i_like', value: '프로' })
+    expect(by('responsibility').filter('회계')).toEqual({ name: 'jobResponsibility', operator: 'i_like', value: '회계' })
+    expect(by('department').filter('영업')).toEqual({ name: 'departmentName', operator: 'i_like', value: '영업' })
+  })
+
+  it("★ every part-of condition is on a field the organization's list lets LIKE reach - one outside is dropped without a word", () => {
+    const source = require('fs').readFileSync(require('path').join(__dirname, '..', '..', '..', '..', 'organization', 'server', 'service', 'employee', 'employee-query.ts'), 'utf8') as string
+    const searchables = JSON.parse(source.match(/searchables: (\[[^\]]*\])/)![1].replace(/'/g, '"')) as string[]
+    const liked = target.criteria.map(one => [one.filter('x')].flat()).flat().filter((f: any) => /like/.test(f.operator)).map((f: any) => f.name)
+    expect(liked.length).toBeGreaterThan(0)
+    expect(liked.filter(name => !searchables.includes(name))).toEqual([])
+  })
+
+  it("the organization's list takes a department by its name", () => {
+    const source = require('fs').readFileSync(require('path').join(__dirname, '..', '..', '..', '..', 'organization', 'server', 'service', 'employee', 'employee-query.ts'), 'utf8') as string
+    expect(source).toMatch(/filtersMap: \{ departmentName: \{ columnName: 'name', relationColumn: 'department' \} \}/)
+  })
+
+  it('carries the user id an invite takes, and finds by name', () => {
+    expect(target.columns.find(one => one.name === 'userId')?.path).toBe('user.id')
+    expect(target.search).toBeTruthy()
+  })
+})
+
+describe('every conversation carries the people tools', () => {
+  const mode = { toolCategories: ['office-reads'], readTargets: ['office.contract'] }
+
+  it('★ offered in every mode, and in front of every turn', () => {
+    for (const category of PEOPLE_CATEGORIES) {
+      expect(modeToolCategories(mode)).toContain(category)
+      expect(modeToolCategories({})).toContain(category)
+      expect(modeFrontCategories(mode)).toContain(category)
+      expect(modeFrontCategories({}, { page: 'anything' })).toContain(category)
+    }
+  })
+
+  it('not in an unattended run - nobody is there to press an invite', () => {
+    expect(unattendedToolCategories(mode)).not.toContain(INVITE_CATEGORY)
+    expect(unattendedToolCategories(mode)).not.toContain(PEOPLE_READ_CATEGORY)
+  })
+})
+
+describe('the invite card knows which conversation it is in', () => {
+  it("★ the conversation door hands the stored session to the tools - the server's value, never the client's", () => {
+    const source = require('fs').readFileSync(require('path').join(__dirname, '..', 'assistant-chat-resolver.ts'), 'utf8') as string
+    expect(source).toMatch(/\.\.\.\(session\?\.id \? \{ conversation: \{ id: session\.id \} \} : \{\}\)/)
+  })
+})

package/server/service/people/people-read.ts

@@ -0,0 +1,56 @@
+/*
+ * Who works here - the organization's `employees` list opened to every conversation as a read target
+ * (operato-application/design/ai/read-targets.md), the way an application opens its own lists.
+ *
+ * Asked to bring 정연희 into a group conversation, the model answered that it had no tool to look up people and
+ * sent the person to search a screen (2026-10-24). The list existed; no conversation could read it.
+ *
+ * Nothing new is built: the read runs the organization module's own query as the person, so its door
+ * (`employee` query, or the domain owner) decides who may read people, and an application without the organization
+ * module has no such door - the tool is not offered there. The selection is the projection: name, department,
+ * position and the user an invite takes. No phone, e-mail, address, bank account or emergency contact is read.
+ */
+import { listReadTarget } from '../data-read/list-read.js'
+import type { ReadTarget } from '../data-read/read-target.js'
+import { PEOPLE_READ_KEY } from './people-keys.js'
+
+/** The fields read of each person - the answer may carry nothing else. */
+export const PEOPLE_SELECTION = 'id name alias jobPosition jobResponsibility department { id name } user { id }'
+
+export function peopleReadTarget(): ReadTarget {
+  const target = listReadTarget({
+    key: PEOPLE_READ_KEY,
+    title: 'ai-assistant.people.title',
+    name: 'people of the organization',
+    listQuery: 'employees',
+    /* People who left are not offered - an invite, a mention or an answer about who does what is about who is here. */
+    fixedFilters: [{ name: 'active', operator: 'eq', value: true }],
+    selection: PEOPLE_SELECTION,
+    columns: [
+      { name: 'name', type: 'string', labelKey: 'ai-assistant.people.name' },
+      { name: 'department', type: 'string', path: 'department.name', labelKey: 'ai-assistant.people.department' },
+      { name: 'position', type: 'string', path: 'jobPosition', labelKey: 'ai-assistant.people.position' },
+      { name: 'responsibility', type: 'string', path: 'jobResponsibility', labelKey: 'ai-assistant.people.responsibility' },
+      { name: 'userId', type: 'string', path: 'user.id', labelKey: 'ai-assistant.people.user' }
+    ],
+    search: 'name, employee number and alias'
+  })
+  /*
+   * Who holds a position, who is in a team - asked 「프로 직책인 사람은 누구야?」 the model put the position into the search
+   * term, which matches names, numbers and aliases only, and answered that nobody held it (2026-10-24).
+   */
+  const contains = (name: string) => (value: any) => ({ name, operator: 'i_like', value })
+  return {
+    ...target,
+    criteria: [
+      ...target.criteria,
+      { name: 'department', type: 'string', labelKey: 'ai-assistant.people.department', description: "part of the department's name", filter: contains('departmentName') },
+      { name: 'position', type: 'string', labelKey: 'ai-assistant.people.position', description: 'part of the position (직책)', filter: contains('jobPosition') },
+      { name: 'responsibility', type: 'string', labelKey: 'ai-assistant.people.responsibility', description: 'part of what they are responsible for (담당)', filter: contains('jobResponsibility') }
+    ],
+    description:
+      'the people who work here, as the organization lists them - name, department, position, responsibility, and the user id ' +
+      'an invite into a conversation takes (empty when the person has no account). Read only who the asker may see. ' +
+      'The text condition finds by name, employee number or alias only - a department, position or responsibility has its own condition.'
+  }
+}

package/server/service/testing/mode-conformance.test.ts

@@ -13,7 +13,7 @@
 import { clearAssistantModes, registerAssistantMode } from '../assistant-mode/registry'
 import { clearToolRegistry, registerToolCategory } from '@things-factory/ai-client-base'
 
-import { runRegisteredMode } from './mode-conformance'
+import { modeCarriesSharedRules, runRegisteredMode } from './mode-conformance'
 
 const client = {
   chatWithTools: async () => ({ text: '한 턴', toolCalls: [], stopReason: 'end_turn' })
@@ -46,3 +46,16 @@ it('an app that wants to see the other case names it — the door the caller can
 
   expect(result.offeredTools).toEqual(['getOpenScene'])
 })
+
+describe('an app prompt that copies a shared rule', () => {
+  afterEach(() => clearAssistantModes())
+
+  it('★ reading the picked records in its own words is a copy of the selection rule', () => {
+    registerAssistantMode({ kind: 'office.copy', systemPrompt: 'explicit-page-selection is what the person picked.' } as any)
+    registerAssistantMode({ kind: 'office.keys', systemPrompt: 'read the [keys] line.' } as any)
+    registerAssistantMode({ kind: 'office.clean', systemPrompt: 'you answer about the books.' } as any)
+    expect(modeCarriesSharedRules('office.copy')).toContain('selection-rule-copy')
+    expect(modeCarriesSharedRules('office.keys')).toContain('selection-rule-copy')
+    expect(modeCarriesSharedRules('office.clean')).toEqual([])
+  })
+})

package/server/service/testing/mode-conformance.ts

@@ -147,6 +147,8 @@ export function modeCarriesSharedRules(kind: string): string[] {
   if (/^\s*Next:/im.test(prompt) || /end the reply with one last line/i.test(prompt)) found.push('next-request-rule-copy')
   if (/finish what was asked in this turn|never ask whether to propose/i.test(prompt)) found.push('finish-rule-copy')
   if (/\[writer → addressee\]/.test(prompt)) found.push('speaker-rule-copy')
+  /* The picked records' note is the framework's form (SELECTION_RULE) - an app reading its own form of it is a copy. */
+  if (/explicit-page-selection|\[keys\]/i.test(prompt)) found.push('selection-rule-copy')
   return found
 }
 

package/test/assistant-dock.test.ts

@@ -13,6 +13,7 @@ const code = (file: string) => read(file).replace(/\/\*[\s\S]*?\*\//g, '').repla
 const dock = code('../client/components/assistant-dock.ts')
 /* Not comment-stripped: the chat has strings like 'image/*' that a comment regex would eat. */
 const chat = read('../client/components/assistant-chat.ts')
+const transport = read('../client/utils/assistant-session-transport.ts')
 
 describe('no empty panel', () => {
   it('not configured, unreadable, no surface and a stuck anchor are each said', () => {
@@ -171,6 +172,20 @@ describe('what twin needed of the dock', () => {
     assert.match(dock, /this\.startCarried\(ask\)\.catch\(\(?\w*\)? => \{\s*notify\(\{ level: 'error'/)
   })
 
+  it('★ a request made on the screen is never dropped while an answer is written - it waits and is taken after', () => {
+    const busy = dock.slice(dock.indexOf('if (this.navigationState.busy) {', dock.indexOf('private async takeAsk')), dock.indexOf('if (this.navigationState.draft', dock.indexOf('private async takeAsk')))
+    assert.match(busy, /this\.takeWhenIdle\(\)\s*return/)
+    assert.doesNotMatch(busy, /takeAssistantAsk\(\)/)
+  })
+
+  it('★ unsent words are asked about before a new request takes the dock - never dropped without asking', () => {
+    assert.match(dock, /if \(this\.navigationState\.draft && !\(await this\.mayLeaveConversation\(\)\)\) \{\s*const waiting = takeAssistantAsk\(\)/)
+  })
+
+  it('a note is drawn without the line only the model reads', () => {
+    assert.match(chat, />\$\{noteForDisplay\(content\)\}<\/span/)
+  })
+
   it('★ and nothing is sent into the previous conversation after it - the request depended on the context that failed', () => {
     assert.match(dock, /this\.startCarried\(ask\)\.catch\([\s\S]*?return undefined\s*\}\)[\s\S]{0,200}?if \(!id\) return\n/)
   })
@@ -203,3 +218,61 @@ describe('closing and opening the dock again (design/ai/shared-dock.md §2-1, §
     assert.match(opening, /if \(this\.hasUpdated && this\.sessionId\) \{\s*this\.loadHistory\(\)\s*this\._startPresence\(\)\s*this\._startMessageSubscription\(\)/)
   })
 })
+
+/*
+ * A screen request (「AI와 작업」) - design/ai/shared-dock.md §2-11-1, the user (2026-10-24): 「"AI와 작업" 기능이 unstable
+ * 하다. 작동 방식을 신뢰할 수 있도록 새로운 세션을 여는지, 기존 세션을 활용하는지 등등을 명확하게 하라.」 One test per rule.
+ */
+describe('a screen request', () => {
+  const take = dock.slice(dock.indexOf('private async takeScreenRequest()'), dock.indexOf('\n  }\n', dock.indexOf('private async takeScreenRequest()')))
+  const send = chat.slice(chat.indexOf('async sendScreenRequest('), chat.indexOf('\n  }\n', chat.indexOf('async sendScreenRequest(')))
+
+  it('goes its own way - a request carrying a selection is a screen request', () => {
+    assert.match(dock, /if \(peekAssistantAsk\(\)\?\.selection\) return this\.takeScreenRequest\(\)/)
+  })
+
+  it('★ 1. to this screen\'s conversation - never a new one; another screen\'s conversation open comes back here', () => {
+    assert.doesNotMatch(take, /newConversation|startCarried|createAISession|controller\.reset|conversationView\+\+/)
+    assert.match(take, /if \(this\.scopeKey\(here\) !== this\.openedFor[^\n]*\) \{\s*(?:\/\*[^*]*\*\/\s*)?this\.keepDraft\(\)\s*this\.surface = here\s*await this\.open\(\)/)
+    assert.match(take, /this\.showingHistory = false/)
+    /* Someone else's open conversation the dock showed by default is not this person's - their own is started (draft along). */
+    assert.match(take, /if \(this\.sessions\.find\(one => one\.id === this\.sessionId\)\?\.participant === false\) await this\.goToOwnConversation\(\)/)
+    /* ...and that is their own most recent one here, a new one only when they have none. */
+    assert.match(dock, /const own = this\.sessions\.find\(one => one\.participant !== false && one\.id !== this\.sessionId\)/)
+    assert.match(dock, /if \(own\) \{\s*if \(this\.controller\.select\(own\.id\)\) this\.conversationView\+\+\s*\} else \{\s*await this\.controller\.reset\(\)/)
+    assert.match(transport, /participant\}\}/)
+    /* No conversation yet: the chat makes this screen's one on sending, through the controller - never a second. */
+    assert.match(send, /if \(!this\.sessionId && this\.prepareSession\) \{\s*await this\.prepareSession\(/)
+  })
+
+  it('★ 2. the selection is noted for that turn, before the request', () => {
+    assert.match(take, /chat\.sendScreenRequest\(request, selectionNote\(ask\.selection!, t\)\)/)
+    const noted = send.indexOf('APPEND_SESSION_NOTE_MUTATION')
+    assert.ok(noted > 0 && noted < send.indexOf('await this.send()'))
+  })
+
+  it('★ 3. sent, always - the request goes out, never as a draft', () => {
+    assert.match(send, /this\.input = text\s*await this\.send\(\)/)
+    assert.doesNotMatch(take, /asking|draft:/)
+    assert.match(take, /ask\.ask\?\.trim\(\) \|\| t\('screen-request-default'/)
+  })
+
+  it('★ 4. what the person was writing is set aside and put back', () => {
+    assert.match(send, /const kept = this\.takeDraft\(\)/)
+    assert.match(send, /finally \{[\s\S]*if \(kept && !this\.input\.trim\(\) && !this\.attachments\.length\) this\.restoreDraft\(kept\)/)
+    assert.match(send, /if \(this\.input\.trim\(\) === text\.trim\(\)\) this\.input = ''/)
+  })
+
+  it('★ 5. not sent: said, and the screen is told', () => {
+    assert.match(take, /const fail = \(reason: string\) => \{\s*notify\(\{ level: 'error', message: reason \}\)\s*settleAssistantAsk\(ask, \{ sent: false, reason \}\)/)
+    assert.match(take, /if \(!outcome\?\.sent\) return fail\(/)
+    assert.match(take, /settleAssistantAsk\(ask, \{ sent: true \}\)/)
+  })
+
+  it('★ 6. an answer being written: said once, and the request goes right after it', () => {
+    const busy = take.slice(take.indexOf('if (this.navigationState.busy)'), take.indexOf('const here'))
+    assert.match(busy, /notify\(\{ level: 'info', message: t\('screen-request-waits'/)
+    assert.match(busy, /this\.takeWhenIdle\(\)\s*return/)
+    assert.doesNotMatch(busy, /takeAssistantAsk\(\)/)
+  })
+})

package/translations/en.json

@@ -424,5 +424,22 @@
   "ai-assistant.text.invite-body-named": "{who} brought you into the conversation \"{name}\".",
   "ai-assistant.text.invite-body": "{who} brought you into a conversation.",
   "ai-assistant.text.board-invite-title": "Board collaboration invite",
-  "ai-assistant.text.board-invite-body": "{who} invited you to collaborate on a board."
+  "ai-assistant.text.board-invite-body": "{who} invited you to collaborate on a board.",
+  "ai-assistant.people.title": "People",
+  "ai-assistant.people.name": "Name",
+  "ai-assistant.people.department": "Department",
+  "ai-assistant.people.position": "Position",
+  "ai-assistant.people.responsibility": "Responsibility",
+  "ai-assistant.people.user": "User",
+  "ai-assistant.people.invite-one": "Invite {name} to this conversation",
+  "ai-assistant.people.invite-pick": "{count} people named {name} - pick whom to invite",
+  "ai-assistant.people.invited": "{names} joined this conversation and was told.",
+  "ai-assistant.dock.selection-note": "Selected {count} · {title}",
+  "ai-assistant.dock.selection-more": "and {count} more",
+  "ai-assistant.dock.screen-request-waits": "An answer is being written - your request goes right after it.",
+  "ai-assistant.dock.screen-request-not-ready": "The conversation is not ready yet. Try again in a moment.",
+  "ai-assistant.dock.screen-request-default": "Read the selected records and suggest what can be done with them now.",
+  "ai-assistant.dock.screen-request-failed": "The request was not sent. Try again.",
+  "ai-assistant.text.screen-request-busy": "an answer is still being written.",
+  "ai-assistant.text.screen-request-no-session": "this screen has no conversation to send to."
 }