@things-factory/ai-assistant 10.1.112 → 10.1.114

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.112",
+  "version": "10.1.114",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -33,10 +33,10 @@
     "@operato/popup": "^10.16.0",
     "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.81",
+    "@things-factory/ai-client-base": "^10.1.114",
     "@things-factory/apptool-base": "^10.1.106",
-    "@things-factory/attachment-base": "^10.1.112",
-    "@things-factory/auth-base": "^10.1.111",
+    "@things-factory/attachment-base": "^10.1.113",
+    "@things-factory/auth-base": "^10.1.113",
     "@things-factory/env": "^10.1.20",
     "@things-factory/shell": "^10.1.106",
     "dompurify": "^3.0.0",
@@ -52,5 +52,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "e300d1b60b98ccb80380afe8df6d2807b1bcff91"
+  "gitHead": "0d8f9bc0ff0cb50431f2c76cb166aaf3809d3cf7"
 }

package/server/service/assistant-mode/resolve.ts

@@ -47,12 +47,13 @@ export interface ModeSettings {
  * The categories a mode opens: its own, the AI 작업판 (design/ai/workspace.md), the attachment reader when it
  * takes files (design/ai/shared-dock.md §9-4), and one propose tool per record it may enter (design/ai/data-entry.md).
  */
-export function modeToolCategories(mode: { toolCategories?: string[]; attachments?: { kinds?: string[] }; entryTargets?: string[] }): string[] | undefined {
+export function modeToolCategories(mode: { toolCategories?: string[]; attachments?: { kinds?: string[] }; entryTargets?: string[]; readTargets?: string[] }): string[] | undefined {
   const extra = [
     /* Every conversation may put a large result on the AI 작업판 (design/ai/workspace.md). */
     'assistant-workspace',
     ...(mode.attachments?.kinds?.length ? ['chat-attachments'] : []),
-    ...(mode.entryTargets ?? []).map(key => `data-entry:${key}`)
+    ...(mode.entryTargets ?? []).map(key => `data-entry:${key}`),
+    ...(mode.readTargets ?? []).map(key => `data-read:${key}`)
   ]
   return [...new Set([...(mode.toolCategories ?? []), ...extra])]
 }

package/server/service/assistant-mode/types.ts

@@ -105,6 +105,8 @@ export interface AssistantModeSpec {
    * with `registerEntryTarget`. Each opens that target's propose tool; its door still decides who gets it.
    */
   entryTargets?: string[]
+  /** The lists of the application the conversation may read - read targets by key (design/ai/read-targets.md). */
+  readTargets?: string[]
   /** i18n key for the line under an empty conversation. */
   footerNoticeKey?: string
   /** i18n key for the line shown once the host reports a proposal staged. */

package/server/service/chat-session/attachment-tool-result.test.ts

@@ -0,0 +1,26 @@
+/*
+ * readChatAttachment's answer (design/ai/shared-dock.md §9-4) - a picture of an earlier turn comes back as the picture.
+ */
+/* The source, not the built package - the two land together and the test must see the change before a build. */
+import { takeToolImages } from '../../../../ai-client-base/server/service/agentic-loop/agentic-loop'
+
+import { attachmentToolResult } from './attachment-tool-result'
+
+describe('a file opened again in a later turn', () => {
+  const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 9])
+
+  it('★ a picture comes back as the picture - not as a request to send it again', () => {
+    const answer: any = attachmentToolResult('a1', { type: 'image', data: png, mediaType: 'image/png', name: '영수증.png' })
+    expect(answer.images).toEqual([{ data: png, mediaType: 'image/png' }])
+    expect(answer.note).not.toMatch(/send it again/)
+    /* What the loop makes of it: the picture as an image part, the rest as the JSON the model reads. */
+    const { value, images } = takeToolImages(answer)
+    expect(images).toHaveLength(1)
+    expect(value).toEqual({ attachmentId: 'a1', name: '영수증.png', type: 'image', note: answer.note, imagesAttached: 1 })
+  })
+
+  it('a text file comes back as its text, and a cut one says so', () => {
+    expect(attachmentToolResult('t1', { type: 'text', text: 'a,b', name: 'x.csv', truncated: false })).toEqual({ attachmentId: 't1', name: 'x.csv', type: 'text', text: 'a,b' })
+    expect(attachmentToolResult('t1', { type: 'text', text: 'a', name: 'x.csv', truncated: true })).toMatchObject({ note: 'the file is longer; this is its beginning.' })
+  })
+})

package/server/service/chat-session/attachment-tool-result.ts

@@ -0,0 +1,18 @@
+/*
+ * What readChatAttachment answers for a file of the conversation (design/ai/shared-dock.md §9-4).
+ *
+ * A text file comes back as its text. A picture comes back as the picture: the reserved `images` field is taken out
+ * of the JSON by the loop (ai-client-base takeToolImages) and sent as an image part of the same turn - so a receipt
+ * sent three turns ago can be read again without asking the person to send it again.
+ *
+ * Pure, so it is tested without storage or the shell.
+ */
+export type FileForModel =
+  | { type: 'image'; data: Buffer; mediaType: string; name: string }
+  | { type: 'text'; text: string; name: string; truncated: boolean }
+
+export function attachmentToolResult(attachmentId: string, file: FileForModel) {
+  return file.type === 'image'
+    ? { attachmentId, name: file.name, type: 'image', images: [{ data: file.data, mediaType: file.mediaType }], note: 'the picture is attached right after this result - look at it.' }
+    : { attachmentId, name: file.name, type: 'text', text: file.text, ...(file.truncated ? { note: 'the file is longer; this is its beginning.' } : {}) }
+}

package/server/service/chat-session/attachment-tools.ts

@@ -2,7 +2,7 @@
  * readChatAttachment - the model opens a file sent in an earlier turn (design/ai/shared-dock.md §9-4).
  *
  * A file reaches the model in full only in the turn it was sent; later turns carry one line naming it.
- * When the model needs it again it asks here. The caller must be able to read the conversation the file
+ * When the model needs it again it asks here - a text file comes back as its text, a picture as the picture itself. The caller must be able to read the conversation the file
  * belongs to - the same gate as reading its messages (ADR-0073 decision 1) - so a file id from elsewhere
  * opens nothing.
  *
@@ -18,6 +18,7 @@ import { isSessionParticipant } from '../chat-session-participant/participant-lo
 import { attachmentForModel, CHAT_ATTACHMENT_REF } from './session-attachments.js'
 import { textCharsOf } from './attachment-policy.js'
 import { getAssistantMode } from '../assistant-mode/registry.js'
+import { attachmentToolResult } from './attachment-tool-result.js'
 
 export const CHAT_ATTACHMENT_CATEGORY = 'chat-attachments'
 
@@ -27,7 +28,7 @@ const readChatAttachment: ToolSpec = {
   doors: ['Query.chatMessages'],
   description:
     'Open a file that was sent earlier in this conversation. History names such files as "[attachment <id>: <name> ...]"; ' +
-    'pass that id. An image comes back as a description request, a text file as its text (cut when long - the answer says so).',
+    'pass that id. An image comes back as the picture itself, a text file as its text (cut when long - the answer says so).',
   schema: {
     type: 'object',
     properties: { attachmentId: { type: 'string', description: 'The id from the "[attachment <id>: ...]" line.' } },
@@ -49,9 +50,7 @@ const readChatAttachment: ToolSpec = {
     }
 
     const file = await attachmentForModel(row, textCharsOf(getAssistantMode(session.kind || '')?.attachments))
-    return file.type === 'image'
-      ? { attachmentId: id, name: file.name, type: 'image', note: 'images are shown to you only in the turn they were sent; ask the person to send it again to look at it.' }
-      : { attachmentId: id, name: file.name, type: 'text', text: file.text, ...(file.truncated ? { note: 'the file is longer; this is its beginning.' } : {}) }
+    return attachmentToolResult(id, file)
   }
 } as ToolSpec
 

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

@@ -0,0 +1,229 @@
+/*
+ * AI 조회 (design/ai/read-targets.md) - the conditions become the application's filters, the rows are read through
+ * its query page by page, the server counts and sums, a long result goes on the workspace as read, and the screen
+ * card says which conditions it does not take.
+ */
+import { modeToolCategories } from '../assistant-mode/resolve'
+import { clearReadTargets, declareReadTarget, groupsOf, MAX_READ_ROWS, queryToolName, readCategoryName, screenAddress, screenToolName, type ReadTarget } from './read-target'
+import { openScreen, queryRecords, readCategoryOf } from './read-tools'
+
+/* The application, as a fake: a bank ledger behind a list query that pages and filters like ListParam. */
+let ledger: any[]
+const calls: any[] = []
+const run = async (_document: string, variables: any) => {
+  calls.push(variables)
+  const keep = (row: any) =>
+    variables.filters.every((f: any) =>
+      f.operator === 'gte' ? row[f.name] >= f.value : f.operator === 'lte' ? row[f.name] <= f.value : f.operator === 'eq' ? row[f.name] === f.value : String(row[f.name] ?? '').includes(f.value)
+    )
+  const all = ledger.filter(keep)
+  const { page, limit } = variables.pagination
+  return { data: { cashTransactions: { items: all.slice((page - 1) * limit, page * limit), total: all.length } } }
+}
+
+const target: ReadTarget = {
+  key: 'office.cash-transaction',
+  labelKey: 'label.office-read-cash-transaction',
+  description: 'bank transactions.',
+  query: 'query ($filters: [Filter!], $pagination: Pagination, $sortings: [Sorting!]) { cashTransactions(filters: $filters, pagination: $pagination, sortings: $sortings) { items { id transactionDate type amount customerName account { name } } total } }',
+  criteria: [
+    { name: 'from', type: 'date', filter: v => ({ name: 'transactionDate', operator: 'gte', value: v }) },
+    { name: 'to', type: 'date', filter: v => ({ name: 'transactionDate', operator: 'lte', value: v }) },
+    { name: 'flow', type: 'enum', values: ['INCOME', 'EXPENSE'], filter: v => ({ name: 'type', operator: 'eq', value: v }) },
+    { name: 'text', type: 'string', filter: v => ({ name: 'customerName', operator: 'search', value: v }) }
+  ],
+  columns: [
+    { name: 'transactionDate', type: 'date' },
+    { name: 'account', path: 'account.name', type: 'string' },
+    { name: 'type', type: 'string' },
+    { name: 'amount', type: 'number', total: true },
+    { name: 'customerName', type: 'string' }
+  ],
+  rowsOf: data => ({ rows: data.cashTransactions.items, total: data.cashTransactions.total }),
+  screen: { route: 'cash-transaction-list', takes: ['flow', 'text'], params: c => ({ flow: c.flow as string, search: c.text as string }) }
+}
+
+const tx = (i: number, date: string, type: string, amount: number, customerName: string) => ({ id: `t${i}`, transactionDate: date, type, amount, customerName, account: { name: '우리은행' } })
+
+beforeEach(() => {
+  clearReadTargets()
+  calls.length = 0
+  ledger = [
+    tx(1, '2026-04-03', 'EXPENSE', 1_000_000, '외주A'),
+    tx(2, '2026-05-10', 'EXPENSE', 250_000, '카카오T'),
+    tx(3, '2026-05-20', 'INCOME', 9_000_000, '고객사'),
+    tx(4, '2026-09-30', 'EXPENSE', 2_000_000, '외주A'),
+    tx(5, '2026-10-01', 'EXPENSE', 70_000, '스타벅스')
+  ]
+})
+
+describe('reading a list', () => {
+  it('★ the conditions become the application\'s filters - the model never names the query\'s columns', async () => {
+    const result: any = await queryRecords(target, { from: '2026-04-01', to: '2026-09-30', flow: 'EXPENSE' }, {}, run)
+    expect(calls[0].filters).toEqual([
+      { name: 'transactionDate', operator: 'gte', value: '2026-04-01' },
+      { name: 'transactionDate', operator: 'lte', value: '2026-09-30' },
+      { name: 'type', operator: 'eq', value: 'EXPENSE' }
+    ])
+    expect(result).toMatchObject({ total: 3, read: 3, complete: true, sums: { amount: 3_250_000 } })
+    expect(result.rows[0]).toEqual({ id: 't1', transactionDate: '2026-04-03', account: '우리은행', type: 'EXPENSE', amount: 1_000_000, customerName: '외주A' })
+    expect(result.proposed).toBeUndefined()
+  })
+
+  it('★ the server groups and sums - by a column largest first, by a date column per month', async () => {
+    const byName: any = await queryRecords(target, { flow: 'EXPENSE', groupBy: 'customerName' }, {}, run)
+    expect(byName.groups[0]).toEqual({ key: '외주A', count: 2, sums: { amount: 3_000_000 } })
+    const byMonth: any = await queryRecords(target, { flow: 'EXPENSE', groupBy: 'transactionDate' }, {}, run)
+    expect(byMonth.groups.map((group: any) => group.key)).toEqual(['2026-04', '2026-05', '2026-09', '2026-10'])
+    expect(groupsOf(target, [], 'nothing')).toBeUndefined()
+  })
+
+  it('a condition that does not fit its type is refused, not guessed at', async () => {
+    const result: any = await queryRecords(target, { from: '지난달', flow: 'OUT' }, {}, run)
+    expect(result).toMatchObject({ rejected: true, error: 'condition-unreadable' })
+    expect(result.refused.map((one: any) => one.name)).toEqual(['from', 'flow'])
+    expect(calls).toHaveLength(0)
+  })
+
+  it('★ a long result goes on the workspace as read - the model gets 20 rows, the card every row', async () => {
+    ledger = Array.from({ length: 450 }, (_, i) => tx(i, `2026-06-${String((i % 28) + 1).padStart(2, '0')}`, 'EXPENSE', 1000 + i, `거래처${i % 7}`))
+    const result: any = await queryRecords(target, { flow: 'EXPENSE', groupBy: 'customerName' }, { t: (key: string) => (key === 'label.office-read-cash-transaction' ? '은행 입출금' : key) }, run)
+    expect(calls.map(one => one.pagination.page)).toEqual([1, 2, 3])
+    expect(result).toMatchObject({ proposed: true, kind: 'workspace', total: 450, read: 450, complete: true, rowsNotShown: 430 })
+    expect(result.rows).toHaveLength(20)
+    const tables = result.forScreen.workspace.blocks.filter((block: any) => block.kind === 'table')
+    expect(tables.map((table: any) => table.rows.length)).toEqual([7, 450])
+    expect(result.forScreen.workspace.title).toBe('은행 입출금 · 450')
+    expect(result.forScreen.workspace.name).toBe('office-cash-transaction')
+  })
+
+  it('★ more than the read limit is said - the sums are of the rows read, never called the total', async () => {
+    ledger = Array.from({ length: MAX_READ_ROWS + 30 }, (_, i) => tx(i, '2026-06-01', 'EXPENSE', 1, 'x'))
+    const result: any = await queryRecords(target, {}, {}, run)
+    expect(result).toMatchObject({ total: MAX_READ_ROWS + 30, read: MAX_READ_ROWS, complete: false, sums: { amount: MAX_READ_ROWS } })
+    expect(result.message).toMatch(/Only 1000 of 1030 rows were read/)
+  })
+
+  it('a query the person may not run is said as it failed', async () => {
+    const result: any = await queryRecords(target, {}, {}, async () => ({ errors: [{ message: 'unauthorized! office:query privilege required' }] }))
+    expect(result).toMatchObject({ rejected: true, error: 'query-failed' })
+  })
+})
+
+describe('the screen card', () => {
+  it('★ the address carries what the screen takes, and the card names what it does not', () => {
+    expect(screenAddress(target, { flow: 'EXPENSE', from: '2026-04-01', text: '외주' })).toEqual({
+      href: 'cash-transaction-list?flow=EXPENSE&search=%EC%99%B8%EC%A3%BC',
+      applied: ['flow', 'text'],
+      notApplied: ['from']
+    })
+    const card: any = openScreen(target, { flow: 'EXPENSE', from: '2026-04-01' }, {})
+    expect(card).toMatchObject({ proposed: true, kind: 'open-page', href: 'cash-transaction-list?flow=EXPENSE', notApplied: ['from'] })
+    expect(card.message).toMatch(/does not take from/)
+  })
+})
+
+describe('declaring and offering', () => {
+  it('★ the tools are locked by the list query\'s door, and a mode opens them by key', () => {
+    const category = readCategoryOf(target, () => run)
+    expect(category.name).toBe(readCategoryName(target.key))
+    expect(category.specs.map(spec => spec.name)).toEqual([queryToolName(target.key), screenToolName(target.key)])
+    expect(category.specs.map(spec => (spec as any).doors)).toEqual([['Query.cashTransactions'], ['Query.cashTransactions']])
+    expect(modeToolCategories({ readTargets: [target.key] })).toContain('data-read:office.cash-transaction')
+  })
+
+  it('a declaration that would mislead is refused at boot', () => {
+    declareReadTarget(target)
+    expect(() => declareReadTarget(target)).toThrow(/declared twice/)
+    expect(() => declareReadTarget({ ...target, key: 'office.x', screen: { ...target.screen!, takes: ['amount'] } })).toThrow(/takes 'amount', which is no condition/)
+    expect(() => declareReadTarget({ ...target, key: 'office.y', columns: [] })).toThrow(/shows no column/)
+  })
+
+  it('every condition has one schema type - Gemini refuses a list of types', () => {
+    const [query] = readCategoryOf(target, () => run).specs as any[]
+    for (const [name, schema] of Object.entries<any>(query.schema.properties)) expect(typeof schema.type).toBe('string')
+  })
+})
+
+describe('one record', () => {
+  it('★ one record by its id - every target takes it, and its every column comes back', async () => {
+    const result: any = await queryRecords(target, { id: 't3' }, {}, run)
+    expect(calls[0].filters).toEqual([{ name: 'id', operator: 'eq', value: 't3' }])
+    expect(result.record).toEqual({ id: 't3', transactionDate: '2026-05-20', account: '우리은행', type: 'INCOME', amount: 9_000_000, customerName: '고객사' })
+    expect(result.message).toMatch(/one record/)
+  })
+
+  it('a list answer names each row by its id - the next question can ask for one', async () => {
+    const result: any = await queryRecords(target, { flow: 'INCOME', text: '고객' }, {}, run)
+    expect(result.record?.id).toBe('t3')
+    const list: any = await queryRecords(target, { flow: 'EXPENSE' }, {}, run)
+    expect(list.rows.every((row: any) => typeof row.id === 'string')).toBe(true)
+  })
+
+  it('a target may not declare id itself', () => {
+    expect(() => declareReadTarget({ ...target, key: 'office.z', criteria: [{ name: 'id', type: 'string', filter: v => ({ name: 'id', operator: 'eq', value: v }) }] })).toThrow(/every target takes it/)
+  })
+})
+
+describe('the text condition', () => {
+  it('★ a target that takes ListParam search sends the words as search - the resolver finds them in its own fields', async () => {
+    const searching: ReadTarget = { ...target, key: 'office.searching', criteria: target.criteria.filter(one => one.name !== 'text'), search: { description: 'the memo and the counterparty' } }
+    const seen: any[] = []
+    await queryRecords(searching, { text: '외주', flow: 'EXPENSE' }, {}, async (_d, variables) => (seen.push(variables), { data: { cashTransactions: { items: [], total: 0 } } }))
+    expect(seen[0].search).toBe('외주')
+    expect(seen[0].filters).toEqual([{ name: 'type', operator: 'eq', value: 'EXPENSE' }])
+    const [query] = readCategoryOf(searching, () => run).specs as any[]
+    expect(query.schema.properties.text.description).toMatch(/the memo and the counterparty/)
+    expect(() => declareReadTarget({ ...target, key: 'office.both', search: { description: 'x' } })).toThrow(/search is the text condition/)
+  })
+})
+
+describe('a list declared in one line', () => {
+  const { listReadTarget } = require('./list-read')
+  const line = {
+    key: 'office.cash-transaction',
+    title: 'menu.cash-transaction-list',
+    name: '자금 입출금 관리',
+    listQuery: 'cashTransactions',
+    selection: 'id transactionDate type amount balance customerName',
+    columns: [
+      { name: 'transactionDate', type: 'date' },
+      { name: 'type', type: 'string' },
+      { name: 'amount', type: 'number', total: true },
+      { name: 'balance', type: 'number' }
+    ],
+    dateField: 'transactionDate',
+    narrowing: { year: 'year', month: 'month', flow: 'type' },
+    search: 'memo and counterparty',
+    route: 'cash-transaction-list',
+    screenTakes: ['year', 'month', 'flow', 'text']
+  }
+
+  it('★ becomes a target with the conditions its fields allow - and only those', async () => {
+    const made: ReadTarget = listReadTarget(line)
+    declareReadTarget(made)
+    expect(made.criteria.map(one => one.name)).toEqual(['from', 'to', 'year', 'month', 'flow', 'minAmount', 'maxAmount'])
+    expect(made.query).toContain('cashTransactions(filters: $filters, pagination: $pagination, sortings: $sortings, search: $search) { items { id transactionDate type amount balance customerName } total }')
+    const bare: ReadTarget = listReadTarget({ ...line, key: 'office.bare', narrowing: undefined, dateField: undefined, search: undefined, columns: [{ name: 'name', type: 'string' }] })
+    expect(bare.criteria).toEqual([])
+    expect(bare.query).not.toContain('$search')
+    expect(bare.screen!.takes).toEqual([])
+  })
+
+  it('★ the to day takes the whole day of a date-time, and the screen gets only what it reads', () => {
+    const made: ReadTarget = listReadTarget(line)
+    const to = made.criteria.find(one => one.name === 'to')!
+    expect(to.filter('2026-09-30')).toEqual({ name: 'transactionDate', operator: 'lte', value: '2026-09-30T23:59:59.999' })
+    expect(made.screen!.params({ year: 2026, month: 9, flow: 'EXPENSE', text: '외주', from: '2026-01-01' })).toEqual({ year: 2026, month: 9, flow: 'EXPENSE', search: '외주' })
+    expect(made.screen!.params({ month: 9 })).toEqual({})
+    const plain: ReadTarget = listReadTarget({ ...line, key: 'plant.x', screenTakes: undefined })
+    expect(plain.screen!.takes).toEqual([])
+    expect(plain.screen!.params({ year: 2026 })).toEqual({})
+  })
+
+  it('a minimum or maximum amount means the amount column, else the first summed one', () => {
+    const made: ReadTarget = listReadTarget({ ...line, key: 'office.claims', columns: [{ name: 'totalAmount', type: 'number', total: true }] })
+    expect(made.criteria.find(one => one.name === 'minAmount')!.filter(5)).toEqual({ name: 'totalAmount', operator: 'gte', value: 5 })
+  })
+})
+

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

@@ -0,0 +1,98 @@
+/*
+ * A list declared in one line (operato-application/design/ai/read-targets.md §3) - the shape most list screens share:
+ * a ListParam query, the fields it reads, a date to range over, a status, an amount, search words, and a screen.
+ * Each application writes its lists as these lines; this turns one into a read target with the conditions it takes.
+ */
+import type { ReadColumn, ReadCriterion, ReadTarget } from './read-target.js'
+
+export interface ListRead {
+  /** `<app>.<record>`. */
+  key: string
+  /** i18n key of the screen's title - the card's name. */
+  title: string
+  /** The screen's name as the person knows it - the model picks the list by it. */
+  name: string
+  /** The ListParam query (`cashTransactions`). */
+  listQuery: string
+  /** The fields of each item it reads - the screen's own selection where there is one. */
+  selection: string
+  columns: ReadColumn[]
+  /** A date (or date-time) field the `from` / `to` conditions range over. */
+  dateField?: string
+  /** Integer year and month fields, and an in/out field (INCOME | EXPENSE) - the `year`, `month`, `flow` conditions. */
+  narrowing?: { year?: string; month?: string; flow?: string }
+  /** A field holding the period as YYYY-MM - the `period` condition. */
+  monthField?: string
+  /** A status field and its values - the `status` condition. */
+  status?: { field: string; values: string[] }
+  /** The resolver's searchables, said for the model - the list takes ListParam search (the `text` condition). */
+  search?: string
+  /** The screen's route. Left out, the list has no screen card. */
+  route?: string
+  /** The conditions the screen reads from its address - `year`, `month`, `flow` and `text` (as `search`). Empty: it opens as it is. */
+  screenTakes?: ('year' | 'month' | 'flow' | 'text')[]
+}
+
+/** The money column a minimum or maximum amount means - `amount` when there is one, else the first summed column. */
+const amountOf = (list: ListRead) => list.columns.find(one => one.name === 'amount' && one.type === 'number')?.name ?? list.columns.find(one => one.total)?.name
+
+export function listReadTarget(list: ListRead): ReadTarget {
+  const search = !!list.search
+  const amount = amountOf(list)
+  const narrowing = list.narrowing ?? {}
+  const criteria: ReadCriterion[] = [
+    ...(list.dateField
+      ? [
+          { name: 'from', type: 'date', labelKey: 'ai-assistant.read.from', description: `the first ${list.dateField}, inclusive`, filter: (v: any) => ({ name: list.dateField!, operator: 'gte', value: v }) },
+          { name: 'to', type: 'date', labelKey: 'ai-assistant.read.to', description: `the last ${list.dateField}, inclusive`, filter: (v: any) => ({ name: list.dateField!, operator: 'lte', value: `${v}${/T/.test(String(v)) ? '' : 'T23:59:59.999'}` }) }
+        ]
+      : []),
+    ...(narrowing.year ? [{ name: 'year', type: 'integer', labelKey: 'ai-assistant.read.year', description: 'a year (2026)', filter: (v: any) => ({ name: narrowing.year!, operator: 'eq', value: v }) }] : []),
+    ...(narrowing.month ? [{ name: 'month', type: 'integer', labelKey: 'ai-assistant.read.month', description: '1-12, with a year', filter: (v: any) => ({ name: narrowing.month!, operator: 'eq', value: v }) }] : []),
+    ...(narrowing.flow
+      ? [{ name: 'flow', type: 'enum', values: ['INCOME', 'EXPENSE'], labelKey: 'ai-assistant.read.flow', description: 'money in or out', filter: (v: any) => ({ name: narrowing.flow!, operator: 'eq', value: v }) }]
+      : []),
+    ...(list.monthField
+      ? [{ name: 'period', type: 'string', labelKey: 'ai-assistant.read.period', description: 'a month as YYYY-MM', filter: (v: any) => ({ name: list.monthField!, operator: 'eq', value: v }) }]
+      : []),
+    ...(list.status
+      ? [{ name: 'status', type: 'enum', values: list.status.values, labelKey: 'ai-assistant.read.status', filter: (v: any) => ({ name: list.status!.field, operator: 'eq', value: v }) }]
+      : []),
+    ...(amount
+      ? [
+          { name: 'minAmount', type: 'number', labelKey: 'ai-assistant.read.min-amount', description: `at least this ${amount}`, filter: (v: any) => ({ name: amount, operator: 'gte', value: v }) },
+          { name: 'maxAmount', type: 'number', labelKey: 'ai-assistant.read.max-amount', description: `at most this ${amount}`, filter: (v: any) => ({ name: amount, operator: 'lte', value: v }) }
+        ]
+      : [])
+  ] as ReadCriterion[]
+
+  const takes = (list.screenTakes ?? []).filter(name => (name === 'text' ? search : !!narrowing[name]))
+  return {
+    key: list.key,
+    labelKey: list.title,
+    description: `the rows of the list 「${list.name}」 (${list.columns.map(one => one.name).join(', ')}).`,
+    query:
+      `query ($filters: [Filter!], $pagination: Pagination, $sortings: [Sorting!]${search ? ', $search: String' : ''}) ` +
+      `{ ${list.listQuery}(filters: $filters, pagination: $pagination, sortings: $sortings${search ? ', search: $search' : ''}) { items { ${list.selection} } total } }`,
+    criteria,
+    columns: list.columns,
+    rowsOf: data => ({ rows: data?.[list.listQuery]?.items ?? [], total: data?.[list.listQuery]?.total ?? 0 }),
+    ...(search ? { search: { description: `the ${list.search}` } } : {}),
+    ...(list.dateField ? { sortings: [{ name: list.dateField, desc: true }] } : {}),
+    ...(list.route
+      ? {
+          screen: {
+            route: list.route,
+            labelKey: list.title,
+            takes,
+            params: (c: Record<string, any>) => ({
+              ...(takes.includes('year') ? { year: c.year } : {}),
+              ...(takes.includes('month') && c.year ? { month: c.month } : {}),
+              ...(takes.includes('flow') ? { flow: c.flow } : {}),
+              ...(takes.includes('text') ? { search: c.text } : {})
+            })
+          }
+        }
+      : {})
+  }
+}