@things-factory/ai-assistant 10.1.241 → 10.1.245

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.241",
+  "version": "10.1.245",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -35,13 +35,14 @@
     "@operato/shell": "^10.29.39",
     "@operato/styles": "^10.0.0",
     "@operato/utils": "^10.29.39",
-    "@things-factory/ai-client-base": "^10.1.241",
-    "@things-factory/apptool-base": "^10.1.234",
-    "@things-factory/attachment-base": "^10.1.241",
-    "@things-factory/auth-base": "^10.1.241",
+    "@things-factory/ai-client-base": "^10.1.245",
+    "@things-factory/apptool-base": "^10.1.245",
+    "@things-factory/attachment-base": "^10.1.245",
+    "@things-factory/auth-base": "^10.1.245",
     "@things-factory/env": "^10.1.149",
-    "@things-factory/setting-base": "^10.1.241",
-    "@things-factory/shell": "^10.1.234",
+    "@things-factory/help": "^10.1.245",
+    "@things-factory/setting-base": "^10.1.245",
+    "@things-factory/shell": "^10.1.245",
     "dompurify": "^3.0.0",
     "exceljs": "4.2.0",
     "graphql-scalars": "^1.22.0",
@@ -57,5 +58,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "d7fe2e1a1eb7c02cb21b897da26d385df014f908"
+  "gitHead": "f7479631094a1c70b486485b556885b069025f88"
 }

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

@@ -1,6 +1,7 @@
 /* Read by the resolver and by the boot report, so the report and the conversation open the same tools. */
 import { entryTargetOf } from '../data-entry/entry-target.js'
 import { detailReadOf, readTargetOf } from '../data-read/read-target.js'
+import { HELP_CATEGORY } from '../help-documents/help-keys.js'
 import { PEOPLE_CATEGORIES } from '../people/people-keys.js'
 /**
  * A category another package opens in every conversation - a dashboard card (ADR-0160 decision 9). It is in reach of
@@ -53,6 +54,8 @@ export function modeToolCategories(mode: { toolCategories?: string[]; attachment
     'assistant-workspace',
     /* Every conversation may read who works here and offer to bring one of them in (people/, ADR-0073 decision 3). */
     ...PEOPLE_CATEGORIES,
+    /* Every conversation may read the application's help (ADR-0181). */
+    HELP_CATEGORY,
     ...(mode.attachments?.kinds?.length ? ['chat-attachments'] : []),
     ...(mode.entryTargets ?? []).map(key => `data-entry:${key}`),
     ...(mode.readTargets ?? []).map(key => `data-read:${key}`),
@@ -143,6 +146,8 @@ export function modeFrontCategories(mode: FrontMode, screen: TurnScreen = {}): s
        * there was no tool to look people up (2026-10-24).
        */
       ...PEOPLE_CATEGORIES,
+      /* Two tools, always in front: 「지출결의는 어디서 올려?」 is asked on any screen (ADR-0181). */
+      HELP_CATEGORY,
       ...(mode.attachments?.kinds?.length ? ['chat-attachments'] : []),
       ...keys.filter(key => (mode.readTargets ?? []).includes(key)).map(key => `data-read:${key}`),
       ...keys.filter(key => (mode.entryTargets ?? []).includes(key)).map(key => `data-entry:${key}`),

package/server/service/assistant-mode/mode-front.test.ts

@@ -33,6 +33,7 @@ describe('the open screen decides what goes in front', () => {
       'assistant-workspace',
       'data-read:organization.employee',
       'chat-invite',
+      'help-documents',
       'chat-attachments',
       'data-read:office.cash-transaction',
       'data-entry:office.cash-transaction'
@@ -69,12 +70,12 @@ describe('the open screen decides what goes in front', () => {
   })
 
   it('★ a record the mode does not read or enter is not put in front', () => {
-    expect(modeFrontCategories({ ...mode, readTargets: [], entryTargets: [] }, { page: 'cash-transaction-list' })).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'chat-attachments'])
+    expect(modeFrontCategories({ ...mode, readTargets: [], entryTargets: [] }, { page: 'cash-transaction-list' })).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'help-documents', 'chat-attachments'])
   })
 
   it('no screen: the mode\'s own, the AI 작업 패널 and the attachment reader', () => {
-    expect(modeFrontCategories(mode)).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'chat-attachments'])
-    expect(modeFrontCategories(mode, { page: 'some-other-page' })).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'chat-attachments'])
+    expect(modeFrontCategories(mode)).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'help-documents', 'chat-attachments'])
+    expect(modeFrontCategories(mode, { page: 'some-other-page' })).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'help-documents', 'chat-attachments'])
   })
 
   it('the screens the boot report walks: none, each list page, each axis', () => {

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

@@ -36,7 +36,7 @@ it('★ the settings come from the registered mode', () => {
     /* The app's persona, then the rules every conversation follows (design/ai/screen-pattern.md §4). */
     systemPrompt: conversationPrompt('you answer about one space'),
     /* Every conversation may put a large result on the AI 작업 패널 (design/ai/workspace.md). */
-    toolCategories: ['twin-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite'],
+    toolCategories: ['twin-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'help-documents'],
     requireToolOnFirstTurn: true,
     temperature: 0.2,
     maxTokens: 2048

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

@@ -68,8 +68,8 @@ describe('declaring a target', () => {
   })
 
   it('a mode opens a target by naming it', () => {
-    expect(modeToolCategories({ toolCategories: ['office-ops'], entryTargets: ['office.expense-line'] })).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'data-entry:office.expense-line'])
-    expect(modeToolCategories({ toolCategories: ['office-ops'] })).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite'])
+    expect(modeToolCategories({ toolCategories: ['office-ops'], entryTargets: ['office.expense-line'] })).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'help-documents', 'data-entry:office.expense-line'])
+    expect(modeToolCategories({ toolCategories: ['office-ops'] })).toEqual(['office-ops', 'assistant-workspace', 'data-read:organization.employee', 'chat-invite', 'help-documents'])
   })
 })
 

package/server/service/help-documents/help-keys.ts

@@ -0,0 +1,2 @@
+/* The help tools' category - every conversation carries it (mode-categories.ts), so it is named apart from the tools. */
+export const HELP_CATEGORY = 'help-documents'

package/server/service/help-documents/help-tools.test.ts

@@ -0,0 +1,40 @@
+/*
+ * The help tools (ADR-0181): the assistant finds a part of the application's help and reads it, in the person's language.
+ */
+jest.mock('@things-factory/help', () => {
+  const { HelpIndex, partsOfDocument } = jest.requireActual('../../../../help/server/help-index')
+  const index = new HelpIndex([
+    ...partsOfDocument('office/guide-employee.ko.html', '<h1>모든 직원</h1><h2 id="spending">경비 · 지출 올리기</h2><p>내 정보 › 내 지출결의 에서 새 결의를 작성합니다.</p>'),
+    ...partsOfDocument('office/guide-employee.html', '<h1>Everyone</h1><h2 id="spending">Spending</h2><p>Write a new claim in My expense claims.</p>')
+  ])
+  return { searchHelp: (q: string, o: any) => index.search(q, o), readHelp: (t: string, s: string, l: string) => index.read(t, s, l) }
+})
+
+import { helpCategory, readHelpDocument, searchHelpDocuments } from './help-tools'
+import { modeFrontCategories, modeToolCategories } from '../assistant-mode/mode-categories'
+
+const korean = { state: { lng: 'ko' } }
+
+describe('the help tools', () => {
+  it('finds a part with its title and its link', () => {
+    expect(searchHelpDocuments({ query: '지출결의 올리기' }, korean)).toEqual({
+      found: 1,
+      parts: [{ topic: 'office/guide-employee', section: 'spending', title: '모든 직원 › 경비 · 지출 올리기', summary: '내 정보 › 내 지출결의 에서 새 결의를 작성합니다.', link: 'help?topic=office%2Fguide-employee&section=spending' }]
+    })
+  })
+
+  it('says when the help has nothing, so the model does not answer from elsewhere', () => {
+    expect(searchHelpDocuments({ query: '주식 매수 방법' }, korean)).toMatchObject({ found: 0, message: expect.stringContaining('say so') })
+  })
+
+  it('reads a part in the person\'s language', () => {
+    expect(readHelpDocument({ topic: 'office/guide-employee', section: 'spending' }, { state: { lng: 'en' } })).toMatchObject({ found: true, title: 'Spending' })
+    expect(readHelpDocument({ topic: 'office/guide-employee', section: 'none' }, korean)).toMatchObject({ found: false })
+  })
+
+  it('reaches no door, and every conversation has it in front', () => {
+    expect(helpCategory.specs.map(spec => spec.doors)).toEqual([[], []])
+    expect(modeToolCategories({})).toContain('help-documents')
+    expect(modeFrontCategories({})).toContain('help-documents')
+  })
+})

package/server/service/help-documents/help-tools.ts

@@ -0,0 +1,86 @@
+/*
+ * The application's help documents, for the assistant (ADR-0181) - the same index the screen's `?` asks
+ * (@things-factory/help). How to do a piece of work, which screen it is on, what a word means: the model finds the part
+ * and reads it, rather than the mode's prompt carrying the manual.
+ *
+ * The help is no one's secret - every screen's `?` opens it for whoever is there - so the tools reach no door. Whether
+ * the person may open the screen a part names is still that screen's own door.
+ */
+import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
+import { readHelp, searchHelp } from '@things-factory/help'
+
+import { HELP_CATEGORY } from './help-keys.js'
+
+/** Where a part opens in the application - the help page at that part. */
+export const helpLink = (topic: string, section = '') => `help?topic=${encodeURIComponent(topic)}${section ? `&section=${encodeURIComponent(section)}` : ''}`
+
+const languageOf = (context: any): string | undefined => context?.state?.lng || context?.state?.language || undefined
+
+export function searchHelpDocuments(args: { query?: string; limit?: number }, context?: any) {
+  const query = String(args?.query ?? '').trim()
+  if (!query) return { found: 0, parts: [], message: 'name what to look for.' }
+  const parts = searchHelp(query, { lang: languageOf(context), limit: Math.min(Math.max(Number(args?.limit) || 5, 1), 10) }).map(hit => ({
+    topic: hit.topic,
+    section: hit.section,
+    title: hit.documentTitle === hit.title ? hit.title : `${hit.documentTitle} › ${hit.title}`,
+    summary: hit.summary,
+    link: helpLink(hit.topic, hit.section)
+  }))
+  return parts.length ? { found: parts.length, parts } : { found: 0, parts: [], message: 'the help has nothing on this - say so; do not answer from general knowledge as if it were this application.' }
+}
+
+export function readHelpDocument(args: { topic?: string; section?: string }, context?: any) {
+  const topic = String(args?.topic ?? '').trim()
+  const section = String(args?.section ?? '').trim()
+  const part = topic ? readHelp(topic, section, languageOf(context)) : null
+  if (!part) return { found: false, message: `no help part ${topic}${section ? `#${section}` : ''} - search again with searchHelp.` }
+  return { found: true, ...part, link: helpLink(part.topic, part.section) }
+}
+
+const searchSpec = {
+  kind: 'read',
+  name: 'searchHelp',
+  doors: [],
+  description:
+    "Search this application's help and manuals (how to do a piece of work, which screen and menu it is on, what a term means). " +
+    'Returns the matching parts with a one-line summary and a link; read one with readHelp.',
+  schema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'The words to look for, in the language of the help - a screen or menu name, a task, a term ("지출결의 지급", "휴가 신청").' },
+      limit: { type: 'number', description: 'How many parts, 1-10. Default 5.' }
+    },
+    required: ['query']
+  },
+  builder: (args: any, context: any) => searchHelpDocuments(args, context)
+} as ToolSpec
+
+const readSpec = {
+  kind: 'read',
+  name: 'readHelp',
+  doors: [],
+  description: 'Read one part of the help (topic and section from searchHelp), or the whole document when section is left out.',
+  schema: {
+    type: 'object',
+    properties: {
+      topic: { type: 'string', description: 'The topic from searchHelp ("office/guide-employee").' },
+      section: { type: 'string', description: 'The section from searchHelp ("leave"). Leave out for the whole document.' }
+    },
+    required: ['topic']
+  },
+  builder: (args: any, context: any) => readHelpDocument(args, context)
+} as ToolSpec
+
+export const helpCategory: ToolCategory = {
+  name: HELP_CATEGORY,
+  description: "the application's help and manuals",
+  guidance: [
+    '- When the person asks how to do something in this application, where a screen or menu is, what the steps are, or what a term on a screen means, call searchHelp, then readHelp on the part that answers it - before you answer.',
+    '- Answer from what readHelp returned, in your own short words, and end with the part as a link: [its title](its link). Never invent a menu, a button or a step the help does not name.',
+    '- When searchHelp finds nothing, say the help does not cover it; then answer only what your other tools show.',
+    '- The help says how the application works; figures and records still come from the other tools.'
+  ].join('\n'),
+  specs: [searchSpec, readSpec]
+}
+
+registerToolCategory(helpCategory)

package/server/service/index.ts

@@ -14,6 +14,7 @@ import './chat-session/session-purge.js'
 import './chat-session/attachment-route.js'
 import { EntryProposalResolver } from './data-entry/entry-resolver.js'
 import './workspace/workspace-tools.js'
+import './help-documents/help-tools.js'
 /* Who works here, and the card that brings one of them into a conversation - every conversation carries both. */
 import './people/index.js'
 import { entities as UnattendedRunEntities } from './unattended-run/index.js'