@things-factory/ai-assistant 10.1.176 → 10.1.177

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.176",
+  "version": "10.1.177",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -34,7 +34,7 @@
     "@operato/popup": "^10.16.0",
     "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
-    "@things-factory/ai-client-base": "^10.1.176",
+    "@things-factory/ai-client-base": "^10.1.177",
     "@things-factory/apptool-base": "^10.1.165",
     "@things-factory/attachment-base": "^10.1.176",
     "@things-factory/auth-base": "^10.1.176",
@@ -54,5 +54,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "24928f127d73de0e9946423bd4c3295f54cce03d"
+  "gitHead": "91da09c945ec5e77ab960074db8f53b9ea8ac534"
 }

package/server/service/chat-message/chat-message.ts

@@ -119,7 +119,8 @@ export class ChatMessage {
    * 로 parse 된 객체. UI 의 fold-able 박스 ("AI 가 이런 도구를 사용했습니다") 가
    * 페이지 reload / loadHistory 후에도 살아있도록 영속.
    *
-   * 형태: ToolUsage[] (assistant.ts 의 시간순 trace, summarizeToolResult 로 압축).
+   * 형태: ToolUsage[] (시간순 trace). result 는 값이 아니라 모양(resultShapeOf — 크기 · 건수 · 키 이름 · 오류 코드,
+   * ADR-0061 결정 8). 급여 · 지분 값이 대화 행 · 백업 · 내보내기로 복제되지 않는다.
    * null 이면 도구 호출 없었던 메시지 (text-only 응답).
    */
   @Column({

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

@@ -4,8 +4,8 @@
  * 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'
+import { clearReadTargets, declareDetailRead, declareReadTarget, detailToolName, groupsOf, MAX_DETAIL_CHARS, MAX_READ_ROWS, queryToolName, readCategoryName, screenAddress, screenToolName, type DetailRead, type ReadTarget } from './read-target'
+import { detailCategoryOf, openScreen, queryDetail, 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[]
@@ -264,18 +264,18 @@ describe('amounts in more than one currency', () => {
   })
 
   it('★ the card shows one figure and one group column per currency', async () => {
-    ledger = [...Array.from({ length: 21 }, (_, i) => fxt(i, 1000, 'KRW', 'A')), fxt(99, 100, 'USD', 'B')]
+    ledger = [...Array.from({ length: 21 }, (_, i) => fxt(i, 1000, 'KRW', 'A')), fxt(98, 500, 'KRW', 'B'), fxt(99, 100, 'USD', 'B')]
     const result: any = await queryRecords(fx, { groupBy: 'customerName' }, { t: (key: string) => (key === 'field.amount' ? '금액' : key) }, run)
     const [metrics, byCustomer] = result.forScreen.workspace.blocks
     expect(metrics.items.map((one: any) => [one.label, one.value])).toEqual([
-      ['rows', '22'],
-      ['금액 (KRW)', '21000'],
+      ['rows', '23'],
+      ['금액 (KRW)', '21500'],
       ['금액 (USD)', '100']
     ])
     expect(byCustomer.columns.map((one: any) => one.name)).toEqual(['key', 'count', 'amount:KRW', 'amount:USD'])
     expect(byCustomer.rows).toEqual([
       { key: 'A', count: 21, 'amount:KRW': 21000, 'amount:USD': 0 },
-      { key: 'B', count: 1, 'amount:KRW': 0, 'amount:USD': 100 }
+      { key: 'B', count: 2, 'amount:KRW': 500, 'amount:USD': 100 }
     ])
   })
 
@@ -301,3 +301,66 @@ describe('amounts in more than one currency', () => {
     expect(bad([{ name: 'amount', type: 'number', currency: 'currency' }, { name: 'currency', type: 'string' }])).toThrow(/not a summed number/)
   })
 })
+
+describe('one answer of a query - a detail read', () => {
+  const summary: DetailRead = {
+    key: 'office.contract-360',
+    description: "one contract's summary - what it bills, what came in, what is still owed.",
+    query: 'query ($id: String!, $year: Int) { contract360(id: $id, year: $year) { code amount currency collected receivable rounds { round paid } } }',
+    args: [
+      { name: 'id', type: 'string', required: true, description: 'the contract id' },
+      { name: 'year', type: 'integer' }
+    ]
+  }
+  const seen: any[] = []
+  const answering = (value: any) => async (document: string, variables: any) => {
+    seen.push({ document, variables })
+    return { data: { contract360: value } }
+  }
+  beforeEach(() => {
+    seen.length = 0
+  })
+
+  it('★ the answer comes as the query returned it, with the arguments the model set in their types', async () => {
+    const value = { code: 'H2026012', amount: 100, currency: 'USD', collected: 40, receivable: 60, rounds: [{ round: 1, paid: 40 }] }
+    const result: any = await queryDetail(summary, { id: 'c-1', year: '2026' }, answering(value))
+    expect(seen[0].variables).toEqual({ id: 'c-1', year: 2026 })
+    expect(result).toMatchObject({ target: 'office.contract-360', answer: value })
+    expect(result.message).toMatch(/never add two currencies/)
+  })
+
+  it('a missing or unreadable argument is refused before anything is read', async () => {
+    const result: any = await queryDetail(summary, { year: 'last year' }, answering({}))
+    expect(seen).toHaveLength(0)
+    expect(result).toMatchObject({ rejected: true, error: 'argument-unreadable' })
+    expect(result.refused).toEqual([{ name: 'id', code: 'required' }, { name: 'year', code: 'not-an-integer' }])
+  })
+
+  it('★ a query the person may not run, nothing found, and an answer too long are each said as such', async () => {
+    expect(await queryDetail(summary, { id: 'c-1' }, async () => ({ errors: [{ message: 'unauthorized! office:query privilege required' }] }))).toMatchObject({ rejected: true, error: 'query-failed' })
+    expect(await queryDetail(summary, { id: 'c-1' }, answering(null))).toMatchObject({ found: false })
+    const long: any = await queryDetail(summary, { id: 'c-1' }, answering({ notes: 'x'.repeat(MAX_DETAIL_CHARS + 1) }))
+    expect(long).toMatchObject({ rejected: true, error: 'answer-too-large' })
+    expect(long.answer).toBeUndefined()
+  })
+
+  it('★ the tool is locked by the query\'s door, and a mode opens it by key like a list', () => {
+    const category = detailCategoryOf(summary, () => answering({}))
+    expect(category.name).toBe(readCategoryName(summary.key))
+    expect(category.specs.map(spec => [spec.name, (spec as any).doors])).toEqual([[detailToolName(summary.key), ['Query.contract360']]])
+    expect(detailToolName(summary.key)).toBe('readOfficeContract360')
+    expect((category.specs[0] as any).schema).toMatchObject({ required: ['id'], properties: { id: { type: 'string' }, year: { type: 'integer' } } })
+    expect(modeToolCategories({ readTargets: [summary.key] })).toContain('data-read:office.contract-360')
+  })
+
+  it('a declaration that would mislead is refused at boot', () => {
+    expect(() => declareDetailRead({ ...summary, key: 'office.a', args: [{ name: 'year', type: 'integer' }] })).toThrow(/takes \$id, which is no argument/)
+    expect(() => declareDetailRead({ ...summary, key: 'office.b', args: [{ name: 'id', type: 'string' }, { name: 'year', type: 'integer' }] })).toThrow(/\$id is required by the query/)
+    expect(() => declareDetailRead({ ...summary, key: 'office.c', args: [...summary.args!, { name: 'month', type: 'integer' }] })).toThrow(/declares 'month', which its query does not take/)
+    expect(() => declareDetailRead({ ...summary, key: 'office.d', query: 'query { a { x } b { y } }', args: [] })).toThrow(/exactly one root field/)
+    declareReadTarget(target)
+    expect(() => declareDetailRead({ ...summary, key: target.key })).toThrow(/declared twice/)
+    declareDetailRead(summary)
+    expect(() => declareReadTarget({ ...target, key: summary.key })).toThrow(/declared twice/)
+  })
+})

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

@@ -11,6 +11,7 @@
  */
 import { readFieldValue, rootFieldOf, type EntryField } from '../data-entry/entry-target.js'
 import type { GraphqlRunner } from '../data-entry/entry-update.js'
+import { parse } from 'graphql'
 
 export interface ReadFilter {
   name: string
@@ -101,7 +102,7 @@ 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`)
+  if (registry.has(target.key) || details.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`)
   for (const column of target.columns.filter(one => one.currency)) {
@@ -127,6 +128,69 @@ export function readTargetOf(key: string | undefined): ReadTarget | undefined {
 
 export function clearReadTargets(): void {
   registry.clear()
+  details.clear()
+}
+
+/* ── One answer of a query ──────────────────────────────────────────────────────────────────────────────────── */
+
+/** An argument of a detail read - one variable of its query, read with the entry fields' rules. */
+export interface DetailArg {
+  name: string
+  type: 'string' | 'integer' | 'number' | 'boolean' | 'date' | 'enum'
+  values?: string[]
+  description?: string
+  required?: boolean
+}
+
+/**
+ * A query whose answer is one thing, not a list - a 360's summary, the receivables, a statement (design/ai/read-targets.md
+ * §9). The application declares the query with the fields its screen reads; the framework runs it as the person, with
+ * the arguments the model set, and hands the answer over as the query returned it. Nothing is summed or cut here: the
+ * selection is the projection, and an answer too long to hand over is refused, never cut.
+ */
+export interface DetailRead {
+  /** `<app>.<thing>` - the tool is named after it. */
+  key: string
+  labelKey?: string
+  /** What it answers, for the model. */
+  description: string
+  /** One query with one root field. Its variables are the arguments - each declared in `args`. */
+  query: string
+  args?: DetailArg[]
+}
+
+/** Characters of an answer handed to the model - a longer one is refused, and the model narrows it. */
+export const MAX_DETAIL_CHARS = 60_000
+
+const details = new Map<string, DetailRead>()
+
+export const detailToolName = (key: string) => `read${pascalOf(key)}`
+
+/** The variables a query declares, and whether each is required (`!`). */
+function variablesOf(document: string): { name: string; required: boolean }[] {
+  const operation: any = parse(document).definitions.find((one: any) => one.kind === 'OperationDefinition')
+  return (operation?.variableDefinitions ?? []).map((one: any) => ({ name: one.variable.name.value, required: one.type.kind === 'NonNullType' && !one.defaultValue }))
+}
+
+export function declareDetailRead(target: DetailRead): void {
+  if (!/^[a-z0-9-]+\.[a-z0-9-]+$/.test(target.key)) throw new Error(`detail read key '${target.key}' is not <app>.<thing>`)
+  if (details.has(target.key) || registry.has(target.key)) throw new Error(`read target '${target.key}' is declared twice`)
+  rootFieldOf(target.query, 'query')
+  const args = target.args ?? []
+  for (const variable of variablesOf(target.query)) {
+    const arg = args.find(one => one.name === variable.name)
+    if (!arg) throw new Error(`detail read '${target.key}' takes $${variable.name}, which is no argument`)
+    if (variable.required && !arg.required) throw new Error(`detail read '${target.key}': $${variable.name} is required by the query - declare it required`)
+  }
+  for (const arg of args) {
+    if (!variablesOf(target.query).some(one => one.name === arg.name)) throw new Error(`detail read '${target.key}' declares '${arg.name}', which its query does not take`)
+    if (arg.type === 'enum' && !arg.values?.length) throw new Error(`argument '${arg.name}' of '${target.key}' lists no values`)
+  }
+  details.set(target.key, target)
+}
+
+export function detailReadOf(key: string | undefined): DetailRead | undefined {
+  return key ? details.get(key) : undefined
 }
 
 /** The conditions the model set, read by their declared types; a value that does not fit is said, never guessed at. */

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

@@ -8,7 +8,7 @@
  */
 import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
 
-import { rootFieldOf } from '../data-entry/entry-target.js'
+import { readFieldValue, 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'
@@ -16,6 +16,11 @@ import {
   declareReadTarget,
   filtersOf,
   currenciesOf,
+  declareDetailRead,
+  detailToolName,
+  MAX_DETAIL_CHARS,
+  type DetailArg,
+  type DetailRead,
   groupsOf,
   queryToolName,
   readCategoryName,
@@ -222,3 +227,72 @@ export function registerReadTarget(target: ReadTarget): void {
   declareReadTarget(target)
   registerToolCategory(readCategoryOf(target))
 }
+
+/* ── One answer of a query (DetailRead) ───────────────────────────────────────────────────────────────────── */
+
+function argSchema(arg: DetailArg): any {
+  const type = arg.type === 'number' ? 'number' : arg.type === 'integer' ? 'integer' : arg.type === 'boolean' ? 'boolean' : 'string'
+  const said = [arg.description, arg.type === 'date' ? 'YYYY-MM-DD' : undefined, arg.type === 'enum' ? `one of: ${arg.values!.join(', ')}` : undefined].filter(Boolean).join('. ')
+  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) {
+  const variables: Record<string, unknown> = {}
+  const refused: { name: string; code: string }[] = []
+  for (const arg of target.args ?? []) {
+    const value = args?.[arg.name]
+    if (value === undefined || value === null || value === '') {
+      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)
+    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.` }
+  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}` }
+  }
+  if (answer.errors?.length) return { rejected: true, error: 'query-failed', message: `it could not be read: ${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.' }
+  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.' }
+}
+
+export function detailCategoryOf(target: DetailRead, run: (context: any) => GraphqlRunner = runAsCaller): ToolCategory {
+  const door = rootFieldOf(target.query, 'query')
+  const name = detailToolName(target.key)
+  return {
+    name: readCategoryName(target.key),
+    description: `data read: ${target.key}`,
+    guidance: `- To answer about ${target.description.replace(/\.$/, '')}, call ${name}. Every number you say comes from its answer.`,
+    specs: [
+      {
+        kind: 'read',
+        name,
+        /* The person must be able to run the query on its screen - the tool is not a second way in. */
+        doors: [door],
+        description: `Read ${target.description}`,
+        schema: {
+          type: 'object',
+          ...((target.args ?? []).some(one => one.required) ? { required: (target.args ?? []).filter(one => one.required).map(one => one.name) } : {}),
+          properties: Object.fromEntries((target.args ?? []).map(arg => [arg.name, argSchema(arg)]))
+        },
+        builder: (args: any, context: any) => queryDetail(target, args, run(context))
+      } as ToolSpec
+    ]
+  }
+}
+
+/** What an application calls at boot to let the assistant read one answer of its API. A mode opens it by key in `readTargets`. */
+export function registerDetailRead(target: DetailRead): void {
+  declareDetailRead(target)
+  registerToolCategory(detailCategoryOf(target))
+}

package/server/service/index.ts

@@ -31,7 +31,7 @@ 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 { registerReadTarget, readCategoryOf, registerDetailRead, detailCategoryOf } 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'