@things-factory/ai-assistant 10.1.206 → 10.1.208

package/server/service/data-entry/data-entry.test.ts

@@ -2,7 +2,7 @@
  * Data entry from material (design/ai/data-entry.md) - the rules a row passes, what the tool hands back,
  * and what the server asks again before it writes.
  */
-import { offsetAt, zonedDateTimes, clearEntryTargets, declareEntryTarget, entryDoorOf, entryToolName, entryTotals, lineHas, normalizeEntryRows, printedTotalOf, verifyRowsAgainstSources, writtenForms, type EntryTarget } from './entry-target'
+import { readFieldValue, recordIdOfKey, resolveReferences, offsetAt, zonedDateTimes, clearEntryTargets, declareEntryTarget, entryDoorOf, entryToolName, entryTotals, lineHas, normalizeEntryRows, printedTotalOf, verifyRowsAgainstSources, writtenForms, type EntryTarget } from './entry-target'
 import { entryCategoryOf, proposeEntries } from './entry-tools'
 import { applyEntryProposal, entryProposalAnswered, findEntryProposal, type EntryApplyDeps } from './entry-apply'
 import { modeToolCategories } from '../assistant-mode/resolve'
@@ -410,3 +410,67 @@ describe("a moment is the domain's wall time", () => {
     expect(result.rows[0].values.startTime).toBe('2026-10-01T08:30:00+09:00')
   })
 })
+
+/*
+ * 2026-10-23: an office link card took `tax-invoice:<uuid>` - the key the link evidence and the open record show - and
+ * looked it up as an approval number. A reference that names a record of an axis reads that axis's key as its id.
+ */
+describe('a reference names the record the model was shown', () => {
+  const ID = 'fe0e8503-ec5f-4da4-9c07-2d342c93d498'
+  const invoice = {
+    name: 'invoice',
+    type: 'reference' as const,
+    axis: 'tax-invoice',
+    reference: {
+      query: 'query ($text: String) { invoices(text: $text) { items { id approvalNo } } }',
+      variables: (text: string) => ({ text }),
+      recordsOf: (data: any, text: string) => (data?.invoices?.items ?? []).filter((one: any) => one.id === text || one.approvalNo === text)
+    }
+  }
+  const asked: string[] = []
+  const run = async (_query: string, variables: any) => {
+    asked.push(variables.text)
+    return { data: { invoices: { items: [{ id: ID, approvalNo: '20260120-10260120-17151515' }] } } }
+  }
+  const resolved = async (text: string, field: any = invoice) => {
+    const [row] = await resolveReferences([field], [{ values: { invoice: { text } }, issues: [] as any[] }], run)
+    return row.issues.length ? row.issues[0].code : row.values.invoice.id
+  }
+  beforeEach(() => (asked.length = 0))
+
+  it('★ the key `<axis>:<uuid>`, the bare uuid and the record\'s own words all find it', async () => {
+    expect(await resolved(`tax-invoice:${ID}`)).toBe(ID)
+    expect(asked).toEqual([ID])
+    expect(await resolved(ID)).toBe(ID)
+    expect(await resolved('20260120-10260120-17151515')).toBe(ID)
+  })
+
+  it('★ the key of a record of another axis is not this record, whatever its uuid', async () => {
+    expect(await resolved(`cash-transaction:${ID}`)).toBe('reference-not-found')
+  })
+
+  it('a reference with no axis reads what was written, as before', async () => {
+    const { axis, ...plain } = invoice
+    expect(await resolved(`tax-invoice:${ID}`, plain)).toBe('reference-not-found')
+    expect(asked).toEqual([`tax-invoice:${ID}`])
+  })
+
+  it('★ a field that holds a record\'s id reads its key as the id - one axis or any of several', () => {
+    const question = { name: 'questionId', type: 'string' as const, axis: 'strategy-question' }
+    expect(readFieldValue(question, ` strategy-question:${ID} `)).toEqual({ read: ID })
+    expect(readFieldValue(question, `initiative:${ID}`)).toEqual({ read: `initiative:${ID}` })
+    const owner = { name: 'ownerId', type: 'string' as const, axis: ['strategy-question', 'initiative'] }
+    expect(readFieldValue(owner, `initiative:${ID}`)).toEqual({ read: ID })
+    expect(readFieldValue({ name: 'note', type: 'string' }, `initiative:${ID}`)).toEqual({ read: `initiative:${ID}` })
+    /* A model that hands a resolved reference the key, not the id. */
+    expect(readFieldValue(invoice, { id: `tax-invoice:${ID}` })).toEqual({ read: { id: ID } })
+  })
+
+  it('a key names an id only when it is one', () => {
+    expect(recordIdOfKey('contract', `contract:${ID}`)).toBe(ID)
+    expect(recordIdOfKey('contract', ID.toUpperCase())).toBe(ID.toUpperCase())
+    expect(recordIdOfKey('contract', 'contract:H2026012')).toBeUndefined()
+    expect(recordIdOfKey('contract', 'H2026012')).toBeUndefined()
+    expect(recordIdOfKey('contract', `contract-round:${ID}`)).toBeUndefined()
+  })
+})

package/server/service/data-entry/entry-target.ts

@@ -36,6 +36,14 @@ export interface EntryField {
    * taken; none or several keep the row out and say so - the server never picks among several.
    */
   reference?: EntryReference
+  /**
+   * The axis of the record the field names (`tax-invoice`, `contract`) - several when it may name a record of each - for a
+   * record the model is shown by its key: an open record's anchor and an application's link evidence write
+   * `<axis>:<id>`. The key is read as the id it names, so what the model was shown is what it may write (2026-10-23: a
+   * card took `tax-invoice:<uuid>` from the evidence, looked it up as an approval number and found nothing). A reference
+   * reads it before its query runs; a string field holding an id reads it as the id.
+   */
+  axis?: string | readonly string[]
 }
 
 export interface EntryReference {
@@ -46,6 +54,22 @@ export interface EntryReference {
   recordsOf(data: any, text: string): { id: string; label?: string }[]
 }
 
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * The id a record's key names - `<axis>:<uuid>` as an anchor writes it, or the uuid alone. Nothing for a word, or for
+ * the key of a record of another axis: that one is not this record, whatever its uuid.
+ */
+export function recordIdOfKey(axis: string | readonly string[], text: string): string | undefined {
+  const value = String(text ?? '').trim()
+  const prefix = (typeof axis === 'string' ? [axis] : axis).map(one => `${one}:`).find(one => value.startsWith(one))
+  const id = prefix ? value.slice(prefix.length) : value
+  return UUID.test(id) ? id : undefined
+}
+
+/** What the model wrote for a field that names a record - the id, when it wrote the record's key. */
+const shownId = (field: EntryField, text: string): string => (field.axis && recordIdOfKey(field.axis, text)) || text
+
 /** A resolved reference, as a row keeps it. */
 export interface ReferenceValue {
   id: string
@@ -381,11 +405,11 @@ export function readFieldValue(field: EntryField, value: unknown): { read?: unkn
       return field.values!.includes(String(value).trim()) ? { read: String(value).trim() } : { code: 'not-in-list' }
     case 'reference':
       /* Resolved already ({ id }), or a name to look up ({ text }) - resolveReferences settles the second. */
-      if (value && typeof value === 'object' && typeof (value as any).id === 'string') return { read: { id: (value as any).id, ...((value as any).label ? { label: String((value as any).label) } : {}) } }
+      if (value && typeof value === 'object' && typeof (value as any).id === 'string') return { read: { id: shownId(field, (value as any).id), ...((value as any).label ? { label: String((value as any).label) } : {}) } }
       if (value && typeof value === 'object' && typeof (value as any).text === 'string') return { read: { text: (value as any).text } }
       return typeof value === 'string' || typeof value === 'number' ? { read: { text: String(value).trim() } } : { code: 'not-a-reference' }
     default:
-      return { read: String(value).trim() }
+      return { read: shownId(field, String(value).trim()) }
   }
 }
 
@@ -651,11 +675,12 @@ export async function resolveReferences<T extends { values: Record<string, unkno
     for (const field of references) {
       const value: any = row.values[field.name]
       if (!value || typeof value !== 'object' || typeof value.text !== 'string') continue
-      const key = `${field.name}\u0000${value.text}`
+      const text = shownId(field, value.text)
+      const key = `${field.name}\u0000${text}`
       if (!asked.has(key)) {
         try {
-          const answer = await run(field.reference!.query, field.reference!.variables(value.text))
-          asked.set(key, answer.errors?.length ? new Error(answer.errors[0].message) : field.reference!.recordsOf(answer.data, value.text) ?? [])
+          const answer = await run(field.reference!.query, field.reference!.variables(text))
+          asked.set(key, answer.errors?.length ? new Error(answer.errors[0].message) : field.reference!.recordsOf(answer.data, text) ?? [])
         } catch (error: any) {
           asked.set(key, error instanceof Error ? error : new Error(String(error)))
         }

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

@@ -153,7 +153,7 @@ function changeSpecs(target: EntryTarget, run: (context: any) => GraphqlRunner):
       doors: [...new Set([rootFieldOf(update.mutation, 'mutation'), readDoor, ...referenceDoorsOf(changeableFields(target))])],
       description:
         `Propose changes to existing records: ${target.description} ` +
-        'Name each record by ref: "current" (the one on screen), "selected" (every row selected on screen) or an id a find tool returned. ' +
+        'Name each record by ref: "current" (the one on screen), "selected" (every row selected on screen), an id a find tool returned, or the record\'s key (`<kind>:<id>`) as you were shown it. ' +
         'The server reads each record, and the card shows what it holds now and what it becomes; nothing changes until the person presses it.',
       schema: {
         type: 'object',
@@ -163,7 +163,7 @@ function changeSpecs(target: EntryTarget, run: (context: any) => GraphqlRunner):
             items: {
               type: 'object',
               properties: {
-                ref: { type: 'string', description: '"current", "selected", or a record id from a find tool - never a guessed id.' },
+                ref: { type: 'string', description: '"current", "selected", a record id from a find tool, or the record\'s key as shown - never a guessed id.' },
                 values: { type: 'object', description: 'Only the fields that change, with their new values.', properties: Object.fromEntries(changeableFields(target).map(field => [field.name, fieldSchema(field)])) }
               },
               required: ['ref', 'values']

package/server/service/data-entry/entry-update.ts

@@ -13,6 +13,7 @@ import {
   changeToolName,
   findToolName,
   readFieldValue,
+  recordIdOfKey,
   resolveReferences,
   zonedDateTimes,
   sameFieldValue,
@@ -52,7 +53,8 @@ export function changeableFields(target: EntryTarget): EntryField[] {
 /**
  * The records the changes name. `current` is the record on screen, `selected` every row selected there -
  * both from the surface's host context, which is **not trusted**: an id from it is only a candidate, read
- * through the application before anything is shown. Any other ref is an id, from the find tool.
+ * through the application before anything is shown. Any other ref is an id, from the find tool, or the key the record
+ * was shown by.
  */
 export function resolveChangeRefs(
   targetKey: string,
@@ -74,7 +76,8 @@ export function resolveChangeRefs(
       if (ids.length) for (const id of ids) picked.push({ id, via: 'selected', values })
       else unresolved.push('selected')
     } else if (ref) {
-      picked.push({ id: ref, via: 'id', values })
+      /* An open record's key - `contract-round:<id>` for `office.contract-round` - names the record of this target's axis. */
+      picked.push({ id: recordIdOfKey(targetKey.split('.').pop()!, ref) ?? ref, via: 'id', values })
     } else {
       unresolved.push('no-ref')
     }

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

@@ -9,7 +9,7 @@
  *
  * Pure but for the GraphQL runner, which comes in as an argument - the rules are tested without a server.
  */
-import { readFieldValue, rootFieldOf, type EntryField } from '../data-entry/entry-target.js'
+import { readFieldValue, recordIdOfKey, rootFieldOf, type EntryField } from '../data-entry/entry-target.js'
 import { encodeListQuery } from '@operato/utils/list-query.js'
 import type { GraphqlRunner } from '../data-entry/entry-update.js'
 import { parse } from 'graphql'
@@ -143,6 +143,8 @@ export interface DetailArg {
   values?: string[]
   description?: string
   required?: boolean
+  /** A record's id: the axis (or axes) of the record, whose key `<axis>:<id>` the model may have been shown (EntryField.axis). */
+  axis?: string | readonly string[]
 }
 
 /**
@@ -200,8 +202,8 @@ export function detailReadOf(key: string | undefined): DetailRead | undefined {
 export function readCriteria(target: ReadTarget, args: any): { criteria: Record<string, unknown>; refused: { name: string; code: string }[] } {
   const criteria: Record<string, unknown> = {}
   const refused: { name: string; code: string }[] = []
-  /* One record by its id - every target takes it (the id a list answer or a find tool gave). */
-  if (typeof args?.id === 'string' && args.id.trim()) criteria.id = args.id.trim()
+  /* One record by its id - every target takes it (the id a list answer or a find tool gave, or the key `<axis>:<id>` an open record is shown by, the axis being the key's last part). */
+  if (typeof args?.id === 'string' && args.id.trim()) criteria.id = recordIdOfKey(target.key.split('.').pop()!, args.id) ?? args.id.trim()
   if (target.search && typeof args?.text === 'string' && args.text.trim()) criteria.text = args.text.trim()
   for (const criterion of target.criteria) {
     const value = args?.[criterion.name]

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

@@ -246,7 +246,7 @@ export async function queryDetail(target: DetailRead, args: any, run: GraphqlRun
       if (arg.required) refused.push({ name: arg.name, code: 'required' })
       continue
     }
-    const { read, code } = readFieldValue({ name: arg.name, type: arg.type === 'string' ? 'text' : arg.type, values: arg.values } as any, value)
+    const { read, code } = readFieldValue({ name: arg.name, type: arg.type === 'string' ? 'text' : arg.type, values: arg.values, axis: arg.axis } as any, value)
     if (read === undefined) refused.push({ name: arg.name, code: code ?? 'unreadable' })
     else variables[arg.name] = read
   }

package/server/service/data-read/record-keys.test.ts

@@ -0,0 +1,36 @@
+/*
+ * A read takes a record by the key it was shown by (2026-10-23) - `<axis>:<uuid>`, as an open record's anchor and an
+ * application's evidence write it. A 360 read and a list read asked by id took the key as the id and found nothing.
+ */
+import { readCriteria, type DetailRead, type ReadTarget } from './read-target'
+import { queryDetail } from './read-tools'
+
+const ID = 'f92c04ec-40c4-4be8-8160-080cff20e750'
+
+describe('a read names the record the model was shown', () => {
+  const lines = { key: 'office.cash-transaction', criteria: [] } as unknown as ReadTarget
+
+  it('★ a list read by id takes the key of its own axis - the target key\'s last part', () => {
+    expect(readCriteria(lines, { id: `cash-transaction:${ID}` }).criteria).toEqual({ id: ID })
+    expect(readCriteria(lines, { id: ID }).criteria).toEqual({ id: ID })
+    /* Another record's key is not this record - asked as written, it finds nothing. */
+    expect(readCriteria(lines, { id: `contract:${ID}` }).criteria).toEqual({ id: `contract:${ID}` })
+  })
+
+  it('★ a whole answer takes the key of the axis its id argument declares', async () => {
+    const summary: DetailRead = {
+      key: 'office.contract-360',
+      description: "one contract's 360.",
+      query: 'query ($id: String!) { contract360(id: $id) { code } }',
+      args: [{ name: 'id', type: 'string', required: true, axis: 'contract' }]
+    }
+    const asked: any[] = []
+    const run = async (_document: string, variables: any) => {
+      asked.push(variables)
+      return { data: { contract360: { code: 'H2026012' } } }
+    }
+    await queryDetail(summary, { id: `contract:${ID}` }, run)
+    await queryDetail(summary, { id: `cash-transaction:${ID}` }, run)
+    expect(asked).toEqual([{ id: ID }, { id: `cash-transaction:${ID}` }])
+  })
+})

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

@@ -16,10 +16,13 @@ import { openSubjectLine, registryAssistantChat } from '@things-factory/ai-clien
 
 import { getAssistantMode, getAssistantModeWarnings } from '../assistant-mode/registry.js'
 import { assistantModeView, resolveModeSettings, type Translate } from '../assistant-mode/resolve.js'
+import { modeFrontCategories, type TurnScreen } from '../assistant-mode/mode-categories.js'
 
 export interface ModeRunResult {
   /** 이 모드가 모델에게 실제로 건넨 도구 이름. */
   offeredTools: string[]
+  /** 건네지 않았지만 모델이 openTools 로 꺼낼 수 있던 도구 — 둘을 합치면 이 모드로 쓸 수 있는 전부(ADR-0061 결정 9). */
+  openableTools: string[]
   /** 모델이 받은 시스템 프롬프트 — 서버의 것인지 확인할 수 있다. */
   systemPrompt: string
   /** 첫 턴에 도구를 강제했는가. */
@@ -37,7 +40,7 @@ export const keyEchoTranslate: Translate = key => key
  */
 export async function runRegisteredMode(
   kind: string,
-  options: { client: any; hostContext?: any; state?: any; toolAccess?: any; reply?: string } = {} as any
+  options: { client: any; hostContext?: any; state?: any; toolAccess?: any; reply?: string; screen?: TurnScreen } = {} as any
 ): Promise<ModeRunResult> {
   const settings = resolveModeSettings({ kind }, keyEchoTranslate)
   let requiredToolOnFirstTurn = false
@@ -47,6 +50,8 @@ export async function runRegisteredMode(
     messages: [{ role: 'user', content: '한 턴' }] as any,
     systemPrompt: settings.systemPrompt,
     toolCategories: settings.toolCategories,
+    /* What the door puts in front on that screen (ADR-0061 decision 9) - a mode too large for one call is offered as a person meets it. */
+    front: { categories: modeFrontCategories(getAssistantMode(kind) ?? {}, options.screen ?? {}) },
     requireToolOnFirstTurn: (requiredToolOnFirstTurn = Boolean(settings.requireToolOnFirstTurn)),
     temperature: settings.temperature,
     maxTokens: settings.maxTokens,
@@ -65,6 +70,7 @@ export async function runRegisteredMode(
 
   return {
     offeredTools: [...result.offeredTools],
+    openableTools: [...result.openableTools],
     systemPrompt: settings.systemPrompt,
     requiredToolOnFirstTurn,
     reply: result.reply
@@ -139,6 +145,7 @@ export function modeCarriesSharedRules(kind: string): string[] {
   const found: string[] = []
   if (/name our plumbing|do not describe our machinery/i.test(prompt)) found.push('absence-rule-copy')
   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')
   return found
 }
 

package/server/service/unattended-run/run-unattended.ts

@@ -187,6 +187,8 @@ export async function runAssistantUnattended(input: UnattendedRunInput, deps: Un
         messages,
         systemPrompt,
         toolCategories: categories,
+        /* No screen and no conversation - the mode's own tools in front, the lists opened as the run needs (ADR-0061 decision 9). */
+        front: { categories: mode.toolCategories ?? [] },
         mode: { kind: mode.kind, ...(input.mode.target ? { target: input.mode.target } : {}) },
         toolAccess: deps.toolAccess(state),
         hostContext: input.hostContext,

package/test/assistant-dock.test.ts

@@ -144,7 +144,7 @@ describe('attachments in the chat follow the mode', () => {
     /* Without it the client sends the File as {} and the server refuses the upload (found on :3700, 2026-09-25). */
     assert.match(chat, /context: \{ hasUpload: true \}/)
     /* Sent with the turn's input - the agent the person picked follows it (design/ai/agent-settings.md §5). */
-    assert.match(chat, /\n\s*attachmentIds,\s*\n\s*agentId: this\.agentId\s*\n\s*\}\)/)
+    assert.match(chat, /\n\s*attachmentIds,\s*\n\s*agentId: this\.agentId,\s*\n\s*page: \(store\.getState\(\) as any\)\?\.route\?\.page \|\| undefined\s*\n\s*\}\)/)
   })
 
   it('a stored file opens through the conversation route', () => {

package/translations/ko.json

@@ -260,7 +260,7 @@
   "ai-assistant.entry.change": "{count}건 수정",
   "ai-assistant.entry.title-create": "{name} 입력안",
   "ai-assistant.entry.title-update": "{name} 수정안",
-  "ai-assistant.entry.changed": "{count}건을 고쳤습니다.",
+  "ai-assistant.entry.changed": "{count}건을 수정했습니다.",
   "ai-assistant.entry.changed-none": "수정된 기록이 없습니다.",
   "ai-assistant.entry.changes": "{count}건",
   "ai-assistant.entry.not-changed": "{count}건은 변경하지 않습니다.",
@@ -399,5 +399,5 @@
   "ai-assistant.run.assistant-run-model-error": "실행 중 AI 모델 호출이 실패했습니다.",
   "ai-assistant.run.assistant-run-abandoned": "실행이 도중에 멈춰 다시 시작했습니다.",
   "ai-assistant.run.ai-not-configured": "이 사업장에는 AI 가 설정되어 있지 않습니다.",
-  "ai-assistant.run.ai-agent-not-available": "이 실행에 고른 AI 에이전트를 여기서 쓸 수 없습니다."
+  "ai-assistant.run.ai-agent-not-available": "이 실행에서 선택한 AI 에이전트는 현재 사용할 수 없습니다."
 }