@things-factory/ai-assistant 10.1.113 → 10.1.116

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 } : {})
+            })
+          }
+        }
+      : {})
+  }
+}

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

@@ -0,0 +1,230 @@
+/*
+ * AI 조회 - an application's list, read through its own query as the person (operato-application/design/ai/read-targets.md).
+ *
+ * The application declares what it lets the assistant read: its list query, the conditions the model may set and
+ * how each becomes one of the query's filters, the columns to show, and the screen that lists the same records.
+ * The framework reads the rows through that query with the person's request state - the same @privilege and
+ * domain as the screen - counts and sums them itself, and puts a long result on the AI 작업판 as the query returned
+ * it. The model is told the count, the sums and a few rows; it never copies a table.
+ *
+ * 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 type { GraphqlRunner } from '../data-entry/entry-update.js'
+
+export interface ReadFilter {
+  name: string
+  operator: string
+  value: unknown
+}
+
+/** A condition the model may set - read with the entry fields' rules, turned into the query's filters by the application. */
+export interface ReadCriterion extends Omit<EntryField, 'required' | 'reference' | 'total'> {
+  filter: (value: any) => ReadFilter | ReadFilter[]
+}
+
+export interface ReadColumn {
+  /** The key in the workspace table. */
+  name: string
+  /** Where the value is in a row - a dotted path into the query's item (`account.name`). Defaults to `name`. */
+  path?: string
+  type: 'string' | 'number' | 'date'
+  labelKey?: string
+  /** A number column the server sums. */
+  total?: boolean
+}
+
+export interface ReadScreen {
+  /** The application's route of the list screen (`cash-transaction-list`). */
+  route: string
+  /** The conditions the screen takes, as its address's query arguments. A condition left out is said on the card. */
+  params: (criteria: Record<string, any>) => Record<string, string | number | undefined>
+  /** The conditions `params` carries - the card names the others as not applied on the screen. */
+  takes: string[]
+  labelKey?: string
+}
+
+export interface ReadTarget {
+  /** `<app>.<record>` - the tools are named after it. */
+  key: string
+  /** i18n key naming the records (「은행 입출금」). */
+  labelKey?: string
+  /** What the records are, for the model. */
+  description: string
+  /**
+   * The list query - takes `$filters: [Filter!]`, `$pagination: Pagination` and `$sortings: [Sorting!]`, and
+   * `$search: String` when `search` is declared.
+   */
+  query: string
+  /**
+   * The list takes ListParam's free-text term, matched by the resolver across its own searchable fields - the
+   * condition `text`. Say what it finds in, for the model.
+   */
+  search?: { description: string }
+  criteria: ReadCriterion[]
+  columns: ReadColumn[]
+  rowsOf: (data: any) => { rows: any[]; total: number }
+  /** Orders the rows; the query's own order when left out. */
+  sortings?: { name: string; desc?: boolean }[]
+  screen?: ReadScreen
+}
+
+/** At most this many rows are read - the AI 작업판 table's own limit (workspace-blocks MAX_TABLE_ROWS). */
+export const MAX_READ_ROWS = 1000
+/** Rows the model is shown; the rest stay on the card. */
+export const ROWS_FOR_MODEL = 20
+/** A page of the list query. */
+export const READ_PAGE = 200
+
+const registry = new Map<string, ReadTarget>()
+
+const pascalOf = (key: string) =>
+  key
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map(part => part[0].toUpperCase() + part.slice(1))
+    .join('')
+
+export const queryToolName = (key: string) => `query${pascalOf(key)}`
+export const screenToolName = (key: string) => `open${pascalOf(key)}Screen`
+export const readCategoryName = (key: string) => `data-read:${key}`
+
+export function declareReadTarget(target: ReadTarget): void {
+  if (!/^[a-z0-9-]+\.[a-z0-9-]+$/.test(target.key)) throw new Error(`read target key '${target.key}' is not <app>.<record>`)
+  if (registry.has(target.key)) throw new Error(`read target '${target.key}' is declared twice`)
+  rootFieldOf(target.query, 'query')
+  if (!target.columns.length) throw new Error(`read target '${target.key}' shows no column`)
+  const names = new Set<string>()
+  for (const criterion of target.criteria) {
+    if (criterion.name === 'id') throw new Error(`read target '${target.key}' declares 'id' - every target takes it`)
+    if (criterion.name === 'text' && target.search) throw new Error(`read target '${target.key}' declares 'text' and search - search is the text condition`)
+    if (names.has(criterion.name)) throw new Error(`read target '${target.key}' names the condition '${criterion.name}' twice`)
+    names.add(criterion.name)
+    if (criterion.type === 'enum' && !criterion.values?.length) throw new Error(`condition '${criterion.name}' of '${target.key}' lists no values`)
+  }
+  if (target.search) names.add('text')
+  for (const taken of target.screen?.takes ?? []) if (!names.has(taken)) throw new Error(`the screen of '${target.key}' takes '${taken}', which is no condition`)
+  registry.set(target.key, target)
+}
+
+export function readTargetOf(key: string | undefined): ReadTarget | undefined {
+  return key ? registry.get(key) : undefined
+}
+
+export function clearReadTargets(): void {
+  registry.clear()
+}
+
+/** The conditions the model set, read by their declared types; a value that does not fit is said, never guessed at. */
+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()
+  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]
+    if (value === undefined || value === null || value === '') continue
+    const { read, code } = readFieldValue(criterion as EntryField, value)
+    if (read === undefined) refused.push({ name: criterion.name, code: code ?? 'unreadable' })
+    else criteria[criterion.name] = read
+  }
+  return { criteria, refused }
+}
+
+export function filtersOf(target: ReadTarget, criteria: Record<string, unknown>): ReadFilter[] {
+  return [
+    ...(typeof criteria.id === 'string' ? [{ name: 'id', operator: 'eq', value: criteria.id }] : []),
+    ...target.criteria.flatMap(criterion => (criterion.name in criteria ? [criterion.filter(criteria[criterion.name])].flat() : []))
+  ]
+}
+
+const valueAt = (row: any, path: string) => path.split('.').reduce((at, part) => (at === null || at === undefined ? undefined : at[part]), row)
+
+/** One row as the columns say - a number column as a number, a missing value as null. */
+export function rowOf(target: ReadTarget, item: any): Record<string, string | number | null> {
+  return Object.fromEntries([
+    /* The id names the record to the model - for one record's detail, a change, or its screen. */
+    ...(item?.id ? [['id', String(item.id)] as [string, string]] : []),
+    ...target.columns.map(column => {
+      const raw = valueAt(item, column.path ?? column.name)
+      if (raw === undefined || raw === null || raw === '') return [column.name, null]
+      if (column.type === 'number') {
+        const number = Number(raw)
+        return [column.name, Number.isFinite(number) ? number : null]
+      }
+      return [column.name, String(raw)]
+    })
+  ])
+}
+
+/**
+ * Reads the rows through the application's query, page by page, up to MAX_READ_ROWS. `complete` is false when the
+ * list holds more - a sum of the rows read is then not the sum of the list, and is never said as one.
+ */
+export async function readRows(target: ReadTarget, filters: ReadFilter[], run: GraphqlRunner, search?: string): Promise<{ rows: Record<string, any>[]; total: number; complete: boolean }> {
+  const rows: Record<string, any>[] = []
+  let total = 0
+  for (let page = 1; rows.length < MAX_READ_ROWS; page++) {
+    const answer = await run(target.query, {
+      filters,
+      ...(search ? { search } : {}),
+      pagination: { page, limit: READ_PAGE },
+      ...(target.sortings ? { sortings: target.sortings } : {})
+    })
+    if (answer.errors?.length) throw new Error(answer.errors.map(one => one.message).join('; '))
+    const read = target.rowsOf(answer.data)
+    total = Number(read?.total) || 0
+    const items = read?.rows ?? []
+    rows.push(...items.slice(0, MAX_READ_ROWS - rows.length).map(item => rowOf(target, item)))
+    if (items.length < READ_PAGE || rows.length >= total) break
+  }
+  return { rows, total, complete: rows.length >= total }
+}
+
+export interface ReadGroup {
+  key: string
+  count: number
+  sums: Record<string, number>
+}
+
+/** The sums of the number columns marked total - the server's, never the model's. */
+export function sumsOf(target: ReadTarget, rows: Record<string, any>[]): Record<string, number> {
+  const sums: Record<string, number> = {}
+  for (const column of target.columns.filter(one => one.total && one.type === 'number')) {
+    sums[column.name] = Math.round(rows.reduce((sum, row) => sum + (typeof row[column.name] === 'number' ? row[column.name] : 0), 0) * 100) / 100
+  }
+  return sums
+}
+
+/** The rows grouped by one column - a date column by its month - each with its count and sums, largest first. */
+export function groupsOf(target: ReadTarget, rows: Record<string, any>[], by: string): ReadGroup[] | undefined {
+  const column = target.columns.find(one => one.name === by)
+  if (!column) return undefined
+  const groups = new Map<string, Record<string, any>[]>()
+  for (const row of rows) {
+    const value = row[by]
+    const key = value === null || value === undefined ? '' : column.type === 'date' ? String(value).slice(0, 7) : String(value)
+    groups.set(key, [...(groups.get(key) ?? []), row])
+  }
+  const list = [...groups].map(([key, members]) => ({ key, count: members.length, sums: sumsOf(target, members) }))
+  const first = target.columns.find(one => one.total)?.name
+  return column.type === 'date'
+    ? list.sort((a, b) => a.key.localeCompare(b.key))
+    : list.sort((a, b) => (first ? Math.abs(b.sums[first] ?? 0) - Math.abs(a.sums[first] ?? 0) : b.count - a.count))
+}
+
+/** The address of the target's list screen with the conditions it takes, and the conditions it does not. */
+export function screenAddress(target: ReadTarget, criteria: Record<string, unknown>): { href: string; applied: string[]; notApplied: string[] } | undefined {
+  const screen = target.screen
+  if (!screen) return undefined
+  const params = new URLSearchParams()
+  for (const [name, value] of Object.entries(screen.params(criteria))) if (value !== undefined && value !== null && value !== '') params.set(name, String(value))
+  const given = Object.keys(criteria)
+  const query = params.toString()
+  return {
+    href: query ? `${screen.route}?${query}` : screen.route,
+    applied: given.filter(name => screen.takes.includes(name)),
+    notApplied: given.filter(name => !screen.takes.includes(name))
+  }
+}

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

@@ -0,0 +1,212 @@
+/*
+ * The tools of an AI 조회 target (operato-application/design/ai/read-targets.md §4, §5).
+ *
+ * query<X> reads the rows through the application's list query as the person, and tells the model the count, the
+ * sums, the groups and a few rows. A longer result goes on the AI 작업판 as a proposal the server builds from the rows
+ * themselves - the table is never written by the model. open<X>Screen reads nothing: it hands the card the address
+ * of the application's list screen with the conditions it takes.
+ */
+import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
+
+import { rootFieldOf } from '../data-entry/entry-target.js'
+import type { GraphqlRunner } from '../data-entry/entry-update.js'
+import { runAsCaller } from '../data-entry/entry-tools.js'
+import { normalizeWorkspace, workspaceContents } from '../workspace/workspace-blocks.js'
+import {
+  declareReadTarget,
+  filtersOf,
+  groupsOf,
+  queryToolName,
+  readCategoryName,
+  readCriteria,
+  readRows,
+  ROWS_FOR_MODEL,
+  screenAddress,
+  screenToolName,
+  sumsOf,
+  type ReadCriterion,
+  type ReadTarget
+} from './read-target.js'
+
+/** The reader's words for a key - the key's own default when the translator has none. */
+const wordsOf = (context: any) => (key: string | undefined, fallback: string) => {
+  if (!key || typeof context?.t !== 'function') return fallback
+  try {
+    const said = context.t(key)
+    return said && said !== key ? String(said) : fallback
+  } catch {
+    return fallback
+  }
+}
+
+function criterionSchema(criterion: ReadCriterion): any {
+  /* One type per field - Gemini's function schema refuses a list of types (2026-10-01). */
+  const type = criterion.type === 'number' ? 'number' : criterion.type === 'integer' ? 'integer' : criterion.type === 'boolean' ? 'boolean' : 'string'
+  const said = [criterion.description, criterion.type === 'date' ? 'YYYY-MM-DD' : undefined, criterion.type === 'enum' ? `one of: ${criterion.values!.join(', ')}` : undefined]
+    .filter(Boolean)
+    .join('. ')
+  return { type, ...(said ? { description: said } : {}) }
+}
+
+export async function queryRecords(target: ReadTarget, args: any, context: any, run: GraphqlRunner) {
+  const { criteria, refused } = readCriteria(target, args)
+  if (refused.length) {
+    return { rejected: true, error: 'condition-unreadable', refused, message: `these conditions do not fit their type: ${refused.map(one => `${one.name} (${one.code})`).join(', ')}. Fix them and call again.` }
+  }
+  let read
+  try {
+    read = await readRows(target, filtersOf(target, criteria), run, typeof criteria.text === 'string' && target.search ? criteria.text : undefined)
+  } catch (error: any) {
+    return { rejected: true, error: 'query-failed', message: `the list could not be read: ${error?.message ?? error}` }
+  }
+  const { rows, total, complete } = read
+  const sums = sumsOf(target, rows)
+  const groupBy = typeof args?.groupBy === 'string' && args.groupBy ? args.groupBy : undefined
+  const groups = groupBy ? groupsOf(target, rows, groupBy) : undefined
+  const words = wordsOf(context)
+  const label = words(target.labelKey, target.key)
+
+  const said = {
+    target: target.key,
+    criteria,
+    total,
+    read: rows.length,
+    complete,
+    sums,
+    ...(groupBy ? (groups ? { groupBy, groups: groups.slice(0, 50), ...(groups.length > 50 ? { moreGroups: groups.length - 50 } : {}) } : { groupBy, groupRefused: 'no such column' }) : {}),
+    rows: rows.slice(0, ROWS_FOR_MODEL),
+    ...(rows.length > ROWS_FOR_MODEL ? { rowsNotShown: rows.length - ROWS_FOR_MODEL } : {})
+  }
+  const incomplete = complete
+    ? ''
+    : ` Only ${rows.length} of ${total} rows were read; the sums and groups are of those rows, not of the list - say so, and ask the person to narrow the conditions.`
+
+  if (rows.length === 1 && args?.show !== 'workspace') {
+    return { ...said, record: rows[0], message: 'one record - answer from its fields; say a field it does not have as not recorded.' }
+  }
+  if (rows.length <= ROWS_FOR_MODEL && args?.show !== 'workspace') {
+    return { ...said, message: `${rows.length} rows of ${total}.${incomplete} Answer from these rows; every number you say comes from them.` }
+  }
+
+  /* The workspace is built here from the rows as read - the model never copies the table. */
+  const columns = target.columns.map(column => ({ name: column.name, label: words(column.labelKey, column.name), type: column.type }))
+  const totalColumns = target.columns.filter(one => one.total)
+  const title = typeof args?.title === 'string' && args.title.trim() ? args.title.trim() : `${label} · ${rows.length}`
+  const { workspace } = normalizeWorkspace({
+    name: typeof args?.name === 'string' && args.name ? args.name : target.key.replace(/\./g, '-'),
+    title,
+    ...(complete ? {} : { summary: `${total} / ${rows.length}` }),
+    blocks: [
+      {
+        kind: 'metrics',
+        items: [{ label: words('ai-assistant.read.count', 'rows'), value: String(rows.length), ...(complete ? {} : { note: `/ ${total}` }) }, ...totalColumns.map(column => ({ label: words(column.labelKey, column.name), value: String(sums[column.name]) }))]
+      },
+      ...(groups
+        ? [
+            {
+              kind: 'table',
+              caption: words(target.columns.find(one => one.name === groupBy)?.labelKey, groupBy!),
+              columns: [{ name: 'key', label: words(target.columns.find(one => one.name === groupBy)?.labelKey, groupBy!), type: 'string' }, { name: 'count', label: words('ai-assistant.read.count', 'rows'), type: 'number' }, ...totalColumns.map(column => ({ name: column.name, label: words(column.labelKey, column.name), type: 'number' }))],
+              rows: groups.map(group => ({ key: group.key, count: group.count, ...group.sums }))
+            }
+          ]
+        : []),
+      { kind: 'table', caption: label, columns, rows }
+    ]
+  })
+  return {
+    proposed: true,
+    kind: 'workspace',
+    icon: 'table_view',
+    label: title,
+    ...said,
+    forScreen: { workspace, contents: workspaceContents(workspace!) },
+    message: `${rows.length} rows of ${total} are on the AI 작업판 as read - the person opens it from the card.${incomplete} Say the point in one or two lines from the sums, groups and rows above; do not write the table out.`
+  }
+}
+
+export function openScreen(target: ReadTarget, args: any, context: any) {
+  const { criteria, refused } = readCriteria(target, args)
+  if (refused.length) return { rejected: true, error: 'condition-unreadable', refused, message: 'fix the conditions and call again.' }
+  const address = screenAddress(target, criteria)
+  if (!address) return { rejected: true, error: 'no-screen', message: 'this list has no screen to open.' }
+  const words = wordsOf(context)
+  return {
+    proposed: true,
+    kind: 'open-page',
+    icon: 'open_in_new',
+    label: words(target.screen!.labelKey ?? target.labelKey, target.key),
+    target: target.key,
+    href: address.href,
+    applied: address.applied,
+    notApplied: address.notApplied,
+    /* The card says them in the reader's words. */
+    notAppliedLabels: address.notApplied.map(name => words(target.criteria.find(one => one.name === name)?.labelKey ?? (name === 'text' || name === 'id' ? `ai-assistant.read.${name}` : undefined), name)),
+    message:
+      'the card opens the screen when the person presses it.' +
+      (address.notApplied.length ? ` The screen does not take ${address.notApplied.join(', ')} - say so.` : '')
+  }
+}
+
+export function readCategoryOf(target: ReadTarget, run: (context: any) => GraphqlRunner = runAsCaller): ToolCategory {
+  const door = rootFieldOf(target.query, 'query')
+  const conditions = {
+    ...Object.fromEntries(target.criteria.map(criterion => [criterion.name, criterionSchema(criterion)])),
+    ...(target.search ? { text: { type: 'string', description: `words to find - ${target.search.description}` } } : {})
+  }
+  const specs: ToolSpec[] = [
+    {
+      kind: 'read',
+      name: queryToolName(target.key),
+      /* The person must be able to read the list on its screen - the tool is not a second way in. */
+      doors: [door],
+      description:
+        `Read ${target.description} Set the conditions the question names. Returns the count, the sums, ` +
+        `groups when groupBy is given (a date column groups by month) and the first ${ROWS_FOR_MODEL} rows; more rows go on the AI 작업판 as read.`,
+      schema: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'One record by its id, from an earlier answer - its detail.' },
+          ...conditions,
+          groupBy: { type: 'string', description: `One column to group by: ${target.columns.map(one => one.name).join(', ')}.` },
+          show: { type: 'string', enum: ['answer', 'workspace'], description: 'workspace to put even a short result on the AI 작업판.' },
+          title: { type: 'string', description: 'The workspace title, in the person\'s language.' },
+          name: { type: 'string', description: 'The workspace key; the same key again makes a new version.' }
+        }
+      },
+      builder: (args: any, context: any) => queryRecords(target, args, context, run(context))
+    } as ToolSpec,
+    ...(target.screen
+      ? [
+          {
+            kind: 'read',
+            name: screenToolName(target.key),
+            doors: [door],
+            description: `Offer the person the screen that lists ${target.description} with these conditions. Reads nothing. The screen takes: ${target.screen.takes.join(', ')}.`,
+            schema: { type: 'object', properties: conditions },
+            builder: (args: any, context: any) => openScreen(target, args, context)
+          } as ToolSpec
+        ]
+      : [])
+  ]
+  return {
+    name: readCategoryName(target.key),
+    description: `data read: ${target.key}`,
+    guidance: [
+      `- To answer from ${target.key} records - a list, or one record found by its name, code or id - call ${queryToolName(target.key)} with the conditions the question names. Every number you say comes from its result - never add up rows yourself; use its sums and groups.`,
+      `- A list, a summary by item or month, or a comparison: call it with groupBy, and let a long result go on the AI 작업판 - then answer in one or two lines.`,
+      `- When the result says complete: false, say how many of how many were read and ask to narrow - never call partial sums the total.`,
+      ...(target.screen ? [`- When the person wants to work on the records themselves (edit, sort, export), call ${screenToolName(target.key)}; say which conditions the screen does not take.`] : [])
+    ].join('\n'),
+    specs
+  }
+}
+
+/**
+ * What an application calls at boot to let the assistant read one of its lists. A mode opens it by naming the key
+ * in `readTargets`.
+ */
+export function registerReadTarget(target: ReadTarget): void {
+  declareReadTarget(target)
+  registerToolCategory(readCategoryOf(target))
+}

package/server/service/index.ts

@@ -28,6 +28,10 @@ export * from './tool-access.js'
 /* Data entry from material - an app registers what it can enter; a mode names it (design/ai/data-entry.md). */
 export * from './data-entry/entry-target.js'
 export { registerEntryTarget, entryCategoryOf } from './data-entry/entry-tools.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 } from './data-read/read-tools.js'
+export * from './data-read/list-read.js'
 /* The AI 작업판 - large results on a page of their own (design/ai/workspace.md). */
 export * from './workspace/workspace-blocks.js'
 /* 무엇이 근거인가 — 도구 결과 밖의 셋(프롬프트 · 대화 · 화면 스냅숏). */

package/test/entry-proposal.test.ts

@@ -5,6 +5,9 @@
 import { readFileSync } from 'fs'
 import { join } from 'path'
 
+const mockNotify = jest.fn()
+jest.mock('@operato/layout', () => ({ notify: (...args: any[]) => mockNotify(...args) }))
+
 import { runProposal, setEntryProposalHandler } from '../client/utils/assistant-proposals'
 import {
   entryGroupOf,
@@ -78,6 +81,34 @@ describe('the entry card', () => {
     expect(outcome).toMatchObject({ verdict: 'accepted', applied: 1, missed: 0 })
   })
 
+  it('a closed door emits one generic notification and keeps its refused verdict', async () => {
+    const refusal = { message: 'required', extensions: { code: 'FORBIDDEN', because: 'role', operation: 'mutation', requires: { category: 'warehouse', privilege: 'mutation' } }, path: ['addExpenseLine'] }
+    const report = jest.fn()
+    const handler = entryProposalHandler(async () => ({ verdict: 'refused', errorCode: 'door-closed', applied: 0, missed: 0, refusal }), t, () => undefined, report)
+    const context = { sessionId: 's', confirm: async () => true, notify: () => {} }
+    expect(await handler(card('k'), context)).toMatchObject({ verdict: 'refused', errorCode: 'door-closed', applied: 0 })
+    expect(report.mock.calls).toEqual([[{ level: 'error', message: 'required', ex: [refusal] }]])
+    const broken = entryProposalHandler(async () => ({ verdict: 'refused', errorCode: 'door-closed', refusal }), t, () => undefined, () => { throw new Error('toast unavailable') })
+    expect(await broken(card('k'), context)).toMatchObject({ verdict: 'refused', errorCode: 'door-closed' })
+    const rejected = entryProposalHandler(async () => ({ verdict: 'refused', errorCode: 'door-closed', refusal }), t, () => undefined, async () => { throw new Error('async delivery unavailable') })
+    expect(await rejected(card('k'), context)).toMatchObject({ verdict: 'refused', errorCode: 'door-closed' })
+  })
+
+  it('successful and stale-review answers emit no refusal notification', async () => {
+    const report = jest.fn()
+    for (const answer of [{ verdict: 'accepted', applied: 1 }, { verdict: 'refused', errorCode: 'review-stale' }] as EntryApplyAnswer[]) {
+      await entryProposalHandler(async () => answer, t, () => undefined, report)(card('k'), { sessionId: 's', confirm: async () => true, notify: () => {} })
+    }
+    expect(report).not.toHaveBeenCalled()
+  })
+
+  it('the default transport passes the serialized refusal to layout, with no explicit action', async () => {
+    mockNotify.mockClear()
+    const refusal = { message: 'required', extensions: { code: 'FORBIDDEN' }, path: ['addExpenseLine'] }
+    await entryProposalHandler(async () => ({ verdict: 'refused', errorCode: 'door-closed', refusal }), t)(card('k'), { sessionId: 's', confirm: async () => true, notify: () => {} })
+    expect(mockNotify.mock.calls).toEqual([[{ level: 'error', message: 'required', ex: [refusal] }]])
+  })
+
   it('the chat draws the review and names the button by the rows it enters', () => {
     const chat = readFileSync(join(__dirname, '..', 'client', 'components', 'assistant-chat.ts'), 'utf8')
     expect(chat).toContain('<ox-assistant-entry-review .proposal=${p}>')
@@ -107,4 +138,3 @@ describe('the entry card', () => {
     expect(entryReadyCount(p)).toBe(2)
   })
 })
-

package/test/open-page.test.ts

@@ -0,0 +1,31 @@
+/*
+ * The screen card (design/ai/read-targets.md §5) - it opens an address of the application only, and says the
+ * conditions the screen does not take. The chat's wiring is read as text: importing it pulls the shell.
+ */
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+import { isAppAddress, isOpenPageProposal, openPageNote } from '../client/utils/open-page'
+
+const t = (key: string, options: any = {}) => String(options.defaultValue ?? key).replace(/\{(\w+)\}/g, (_, name) => String(options[name] ?? ''))
+
+describe('the screen card', () => {
+  it('★ opens an address of the application - never another origin or a script', () => {
+    expect(isAppAddress('cash-transaction-list?flow=EXPENSE')).toBe(true)
+    for (const href of ['https://evil.example/x', '//evil.example/x', 'javascript:alert(1)', ' JavaScript:alert(1)', '', 42]) expect(isAppAddress(href)).toBe(false)
+    expect(isOpenPageProposal({ kind: 'open-page', href: 'javascript:alert(1)' })).toBe(false)
+  })
+
+  it('★ says the conditions the screen does not take', () => {
+    expect(openPageNote({ notAppliedLabels: ['기간', '금액'] }, t)).toBe('the screen does not take: 기간, 금액')
+    expect(openPageNote({ notAppliedLabels: [] }, t)).toBe('')
+  })
+
+  it('the chat draws it before the generic run button, and opens it through the dock', () => {
+    const chat = readFileSync(join(__dirname, '../client/components/assistant-chat.ts'), 'utf8')
+    const cards = chat.slice(chat.indexOf('if (isWorkspaceProposal(p))'), chat.indexOf('const card = proposalCardState('))
+    expect(cards).toMatch(/if \(isOpenPageProposal\(p\)\) return this\.renderOpenPageCard\(p\)/)
+    const card = chat.slice(chat.indexOf('private renderOpenPageCard('), chat.indexOf('private renderWorkspaceCard('))
+    expect(card).toMatch(/new CustomEvent\('assistant-open-page', \{ detail: \{ href: p\.href \}/)
+  })
+})

package/translations/en.json

@@ -249,6 +249,20 @@
   "ai-assistant.workspace.versions": "versions",
   "ai-assistant.workspace.version": "version {version} of {of}",
   "ai-assistant.workspace.open": "open in workspace",
+  "ai-assistant.screen.open": "open the screen",
+  "ai-assistant.screen.not-applied": "the screen does not take: {conditions}",
+  "ai-assistant.read.count": "rows",
+  "ai-assistant.read.from": "from",
+  "ai-assistant.read.to": "to",
+  "ai-assistant.read.year": "year",
+  "ai-assistant.read.month": "month",
+  "ai-assistant.read.flow": "in or out",
+  "ai-assistant.read.period": "month",
+  "ai-assistant.read.status": "status",
+  "ai-assistant.read.min-amount": "minimum amount",
+  "ai-assistant.read.max-amount": "maximum amount",
+  "ai-assistant.read.text": "search words",
+  "ai-assistant.read.id": "record",
   "ai-assistant.workspace.contains-table": "{count} tables",
   "ai-assistant.workspace.contains-chart": "{count} charts",
   "ai-assistant.workspace.contains-metrics": "{count} figures",