@things-factory/ai-assistant 10.1.212 → 10.1.214

package/server/service/data-read/read-tools.ts

@@ -236,8 +236,21 @@ function argSchema(arg: DetailArg): any {
   return { type, ...(said ? { description: said } : {}) }
 }
 
-/** Runs the query as the person with the arguments the model set; the answer as the query returned it. */
-export async function queryDetail(target: DetailRead, args: any, run: GraphqlRunner) {
+/**
+ * What running a detail read as the person gave - the root field's value, or why there is none. Shared by the tool,
+ * which hands the value to the model, and by every other reader of a detail read (a dashboard card, ADR-0160
+ * decision 2), which has its own limits: the arguments, the door and the query are one, the size rule is the tool's.
+ */
+export interface DetailRun {
+  /** The root field's value - absent when `error` says why. */
+  value?: unknown
+  error?: 'argument-unreadable' | 'query-failed' | 'not-found'
+  refused?: { name: string; code: string }[]
+  message?: string
+}
+
+/** Runs the query as the person with the arguments given - read by their declared types, a missing required one refused. */
+export async function runDetail(target: DetailRead, args: any, run: GraphqlRunner): Promise<DetailRun> {
   const variables: Record<string, unknown> = {}
   const refused: { name: string; code: string }[] = []
   for (const arg of target.args ?? []) {
@@ -250,17 +263,30 @@ export async function queryDetail(target: DetailRead, args: any, run: GraphqlRun
     if (read === undefined) refused.push({ name: arg.name, code: code ?? 'unreadable' })
     else variables[arg.name] = read
   }
-  if (refused.length) return { rejected: true, error: 'argument-unreadable', refused, message: `these arguments are missing or do not fit their type: ${refused.map(one => `${one.name} (${one.code})`).join(', ')}. Fix them and call again.` }
+  if (refused.length) return { error: 'argument-unreadable', refused }
   let answer
   try {
     answer = await run(target.query, variables)
   } catch (error: any) {
-    return { rejected: true, error: 'query-failed', message: `it could not be read: ${error?.message ?? error}` }
+    return { error: 'query-failed', message: String(error?.message ?? error) }
   }
-  if (answer.errors?.length) return { rejected: true, error: 'query-failed', message: `it could not be read: ${answer.errors.map(one => one.message).join('; ')}` }
+  if (answer.errors?.length) return { error: 'query-failed', message: answer.errors.map(one => one.message).join('; ') }
   const root = rootFieldOf(target.query, 'query').replace(/^Query\./, '')
   const value = answer.data?.[root]
-  if (value === null || value === undefined) return { target: target.key, found: false, message: 'nothing was found for these arguments - say so; do not fill it in.' }
+  if (value === null || value === undefined) return { error: 'not-found' }
+  return { value }
+}
+
+/** Runs the query as the person with the arguments the model set; the answer as the query returned it. */
+export async function queryDetail(target: DetailRead, args: any, run: GraphqlRunner) {
+  const ran = await runDetail(target, args, run)
+  if (ran.error) {
+    if (ran.error === 'argument-unreadable')
+      return { rejected: true, error: 'argument-unreadable', refused: ran.refused, message: `these arguments are missing or do not fit their type: ${ran.refused.map(one => `${one.name} (${one.code})`).join(', ')}. Fix them and call again.` }
+    if (ran.error === 'query-failed') return { rejected: true, error: 'query-failed', message: `it could not be read: ${ran.message}` }
+    return { target: target.key, found: false, message: 'nothing was found for these arguments - say so; do not fill it in.' }
+  }
+  const value = ran.value
   const size = JSON.stringify(value).length
   if (size > MAX_DETAIL_CHARS) return { rejected: true, error: 'answer-too-large', size, message: `the answer runs to ${size} characters, more than ${MAX_DETAIL_CHARS} - narrow the arguments, or read the list it is made of.` }
   return { target: target.key, answer: value, message: 'answer from these fields; every number you say comes from them. Amounts are in the currency beside them - never add two currencies into one number.' }

package/server/service/index.ts

@@ -14,6 +14,8 @@ import './chat-session/session-purge.js'
 import './chat-session/attachment-route.js'
 import { EntryProposalResolver } from './data-entry/entry-resolver.js'
 import './workspace/workspace-tools.js'
+/* Who works here, and the card that brings one of them into a conversation - every conversation carries both. */
+import './people/index.js'
 import { entities as UnattendedRunEntities } from './unattended-run/index.js'
 
 export * from './types.js'
@@ -35,8 +37,9 @@ export { registerEntryTarget, entryCategoryOf, runAsCaller } from './data-entry/
 export { proposeChanges, MAX_CHANGES } from './data-entry/entry-update.js'
 /* Reading an application's lists - an app registers what it lets read; a mode names it (design/ai/read-targets.md). */
 export * from './data-read/read-target.js'
-export { registerReadTarget, readCategoryOf, registerDetailRead, detailCategoryOf } from './data-read/read-tools.js'
+export { registerReadTarget, readCategoryOf, registerDetailRead, detailCategoryOf, runDetail, type DetailRun } from './data-read/read-tools.js'
 export * from './data-read/list-read.js'
+export * from './people/index.js'
 /* The AI 작업판 - large results on a page of their own (design/ai/workspace.md). */
 export * from './workspace/workspace-blocks.js'
 /* 무엇이 근거인가 — 도구 결과 밖의 셋(프롬프트 · 대화 · 화면 스냅숏). */
@@ -65,6 +68,9 @@ export * from './chat-session-participant/mention-invite.js'
 export * from './chat-session-participant/presence.js'
 export * from './chat-message/index.js'
 export * from './chat-session-participant/index.js'
+/* Reading the stored proposals of a conversation and whether one is answered - a package that applies its own card reads them as entry does. */
+export { PROPOSAL_OUTCOME_PREFIX } from './chat-message/proposal-outcome.js'
+export { assertMayWriteSession } from './chat-session/session-write-gate.js'
 /* A mode run with no person in it - a scheduled draft (operato-application/design/ai/unattended-run.md). */
 export * from './unattended-run/index.js'
 

package/server/service/people/index.ts

@@ -0,0 +1,13 @@
+/*
+ * The people tools every conversation carries - the people list (people-read.ts) and the invite card (invite-tools.ts).
+ * Registered once, at boot, as the AI 작업판 is.
+ */
+import { registerReadTarget } from '../data-read/read-tools.js'
+import { peopleReadTarget } from './people-read.js'
+import './invite-tools.js'
+
+registerReadTarget(peopleReadTarget())
+
+export * from './people-keys.js'
+export { peopleReadTarget, PEOPLE_SELECTION } from './people-read.js'
+export { proposeInvite, findPeopleNamed, inviteCategory, MAX_INVITE_CANDIDATES, type InviteCandidate } from './invite-tools.js'

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
 }