@things-factory/ai-assistant 10.1.214 → 10.1.215

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.214",
+  "version": "10.1.215",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -35,12 +35,12 @@
     "@operato/shell": "^10.29.39",
     "@operato/styles": "^10.0.0",
     "@operato/utils": "^10.29.39",
-    "@things-factory/ai-client-base": "^10.1.213",
+    "@things-factory/ai-client-base": "^10.1.215",
     "@things-factory/apptool-base": "^10.1.208",
-    "@things-factory/attachment-base": "^10.1.213",
-    "@things-factory/auth-base": "^10.1.213",
+    "@things-factory/attachment-base": "^10.1.215",
+    "@things-factory/auth-base": "^10.1.215",
     "@things-factory/env": "^10.1.149",
-    "@things-factory/setting-base": "^10.1.213",
+    "@things-factory/setting-base": "^10.1.215",
     "@things-factory/shell": "^10.1.208",
     "dompurify": "^3.0.0",
     "exceljs": "4.2.0",
@@ -55,5 +55,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "15a9f9b0b21a3ad50159d4a4f81e861362f6ef72"
+  "gitHead": "7de5e80eb1f4e2e268746aee39f820e7563f454d"
 }

package/server/service/assistant-chat-resolver.ts

@@ -54,7 +54,7 @@ import { attachmentForModel, describeAttachment, findChatAttachment } from './ch
 import { readTurnAttachments } from './chat-session/turn-attachments.js'
 import { getAssistantMode } from './assistant-mode/registry.js'
 import { resolveModeSettings } from './assistant-mode/resolve.js'
-import { modeFrontCategories, selectionAxesOf } from './assistant-mode/mode-categories.js'
+import { modeFrontCategories, selectionAxesOf, turnSystemPrompt } from './assistant-mode/mode-categories.js'
 import { usedToolNames } from './chat-message/used-tools.js'
 import { splitNextRequest } from './assistant-mode/screen-rules.js'
 import { requestTranslator } from './request-translator.js'
@@ -321,7 +321,7 @@ export class AssistantChatResolver {
           state: context.state
         })
       : undefined
-    const systemPrompt = subjectLine ? `${settings.systemPrompt}\n\n${subjectLine}` : settings.systemPrompt
+    const systemPrompt = turnSystemPrompt(settings.systemPrompt, { subjectLine, page: input.page })
 
     const lastUserMessage = input.messages[input.messages.length - 1]
     let userMessageId: string | undefined

package/server/service/assistant-mode/conversation-category.test.ts

@@ -2,13 +2,13 @@
  * A category another package opens in every conversation (ADR-0160 decision 9) - in reach everywhere, in front only on
  * the pages it names, never in an unattended run.
  */
-import { clearConversationCategories, modeFrontCategories, modeScreens, modeToolCategories, registerConversationCategory, unattendedToolCategories } from './mode-categories'
+import { clearConversationCategories, modeFrontCategories, modeScreens, modeToolCategories, registerConversationCategory, turnSystemPrompt, unattendedToolCategories } from './mode-categories'
 
 const mode = { toolCategories: ['office-ops'], readTargets: ['office.receivables'] }
 
 beforeEach(() => {
   clearConversationCategories()
-  registerConversationCategory({ name: 'dashboard-card', frontPages: ['my-dashboard'] })
+  registerConversationCategory({ name: 'dashboard-card', frontPages: ['my-dashboard'], frontAxes: ['dashboard-card'] })
 })
 
 afterAll(() => clearConversationCategories())
@@ -25,6 +25,19 @@ describe('a category every conversation opens', () => {
     expect(modeFrontCategories(mode, {})).not.toContain('dashboard-card')
   })
 
+  it('★ a record of its axis picked or anchored puts it in front, on any page - a picked card is changed by its tools', () => {
+    expect(modeFrontCategories(mode, { page: 'receivable-page', selectionAxes: ['dashboard-card'] })).toContain('dashboard-card')
+    expect(modeFrontCategories(mode, { subjectAxis: 'dashboard-card' })).toContain('dashboard-card')
+    expect(modeFrontCategories(mode, { page: 'receivable-page', selectionAxes: ['contract'] })).not.toContain('dashboard-card')
+  })
+
+  it('★ its page rule is said in the turns asked from its pages, and only there', () => {
+    registerConversationCategory({ name: 'dashboard-card', frontPages: ['my-dashboard'], pageRule: 'end in a card.' })
+    expect(turnSystemPrompt('persona', { page: 'my-dashboard', subjectLine: 'open: x' })).toBe('persona\n\nopen: x\n\nend in a card.')
+    expect(turnSystemPrompt('persona', { page: 'receivable-page' })).toBe('persona')
+    expect(turnSystemPrompt('persona', {})).toBe('persona')
+  })
+
   it('an unattended run never opens it - nobody is there to press the card', () => {
     expect(unattendedToolCategories(mode)).not.toContain('dashboard-card')
   })

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

@@ -13,7 +13,7 @@ export {
 } from './registry.js'
 export { resolveModeSettings, assistantModeView } from './resolve.js'
 /* A category another package opens in every conversation, in front on the pages it names (ADR-0160 decision 9). */
-export { registerConversationCategory, conversationCategoriesOf, type ConversationCategory } from './mode-categories.js'
+export { registerConversationCategory, conversationCategoriesOf, turnSystemPrompt, type ConversationCategory } from './mode-categories.js'
 export { ABSENCE_RULE, FINISH_RULE, NEXT_REQUEST_RULE, SELECTION_RULE, SPEAKER_RULE, conversationPrompt, isPersonRequest, splitNextRequest } from './screen-rules.js'
 export type { AssistantModeSpec, AssistantModeSlash, AssistantModeWarning, UnattendedLimits } from './types.js'
 export type { AssistantModeRef, ModeSettings, AssistantModeView, AssistantModeSlashView, Translate } from './resolve.js'

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

@@ -11,6 +11,16 @@ export interface ConversationCategory {
   name: string
   /** The application routes whose conversations put it in front (`my-dashboard`). */
   frontPages?: string[]
+  /**
+   * The axes of the records whose selection or anchor puts it in front (`dashboard-card`) - a card picked to change is
+   * changed by this category's tools, wherever the dock is open.
+   */
+  frontAxes?: string[]
+  /**
+   * What a turn asked from one of its front pages must end in - said in that turn's system prompt only. On 나의 대시보드
+   * a request to see a figure is a card; asked 「이번 달 지출 합계」 there, the model answered 「0원」 in words (2026-10-25).
+   */
+  pageRule?: string
 }
 
 const conversationCategories = new Map<string, ConversationCategory>()
@@ -27,6 +37,12 @@ export function clearConversationCategories(): void {
   conversationCategories.clear()
 }
 
+/** The system prompt of one turn - the mode's, the open record's line, and the rules of the page it is asked from. */
+export function turnSystemPrompt(modePrompt: string, screen: { page?: string; subjectLine?: string } = {}): string {
+  const pageRules = screen.page ? conversationCategoriesOf().filter(one => one.pageRule && (one.frontPages ?? []).includes(screen.page!)).map(one => one.pageRule!) : []
+  return [modePrompt, screen.subjectLine, ...pageRules].filter(Boolean).join('\n\n')
+}
+
 /**
  * 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).
@@ -131,7 +147,7 @@ export function modeFrontCategories(mode: FrontMode, screen: TurnScreen = {}): s
       ...keys.filter(key => (mode.readTargets ?? []).includes(key)).map(key => `data-read:${key}`),
       ...keys.filter(key => (mode.entryTargets ?? []).includes(key)).map(key => `data-entry:${key}`),
       ...conversationCategoriesOf()
-        .filter(one => !!screen.page && (one.frontPages ?? []).includes(screen.page))
+        .filter(one => (!!screen.page && (one.frontPages ?? []).includes(screen.page)) || (one.frontAxes ?? []).some(axis => axis === screen.subjectAxis || !!screen.selectionAxes?.includes(axis)))
         .map(one => one.name)
     ])
   ]

package/server/service/assistant-mode/open-subject-door.test.ts

@@ -8,10 +8,12 @@ const door = readFileSync(join(__dirname, '../assistant-chat-resolver.ts'), 'utf
 
 describe('the door', () => {
   it('★ builds the line from the stored session anchor every turn, never from what the screen sent', () => {
-    const block = door.slice(door.indexOf('const subjectLine = session'), door.indexOf('const systemPrompt = subjectLine'))
+    const block = door.slice(door.indexOf('const subjectLine = session'), door.indexOf('const systemPrompt = turnSystemPrompt('))
     expect(block).toMatch(/anchorType: \(session as any\)\.anchorType/)
     expect(block).toMatch(/anchorId: \(session as any\)\.anchorId/)
     expect(block).not.toMatch(/hostContext/)
+    /* The page adds its category's rule, never a line of the screen's. */
+    expect(door).toMatch(/const systemPrompt = turnSystemPrompt\(settings\.systemPrompt, \{ subjectLine, page: input\.page \}\)/)
   })
 
   it('★ the model and the grounding check both read the prompt with the line', () => {

package/server/service/chat-session/session-cleanup.test.ts

@@ -0,0 +1,83 @@
+/* Keeping the conversation list short - design/ai/shared-dock.md §2-7. */
+
+import { listedEntries } from './session-inbox'
+import { archiveDaysOf, cleanupReason, DEFAULT_ARCHIVE_DAYS, emptyAndAbandoned, idleDays, isArchived } from './session-cleanup'
+
+const now = new Date('2026-10-25T12:00:00Z')
+const daysAgo = (days: number) => new Date(now.getTime() - days * 24 * 60 * 60 * 1000)
+
+describe('archive', () => {
+  it('defaults to 60 days and reads a positive number; 0 or false turns it off', () => {
+    expect(DEFAULT_ARCHIVE_DAYS).toBe(60)
+    expect(archiveDaysOf(undefined)).toBe(60)
+    expect(archiveDaysOf('90')).toBe(90)
+    expect(archiveDaysOf(0)).toBeNull()
+    expect(archiveDaysOf(false)).toBeNull()
+  })
+
+  it('counts idle days from the last message, or from the start when there is none', () => {
+    expect(idleDays({ lastMessageAt: daysAgo(3), createdAt: daysAgo(100) }, now)).toBe(3)
+    expect(idleDays({ lastMessageAt: null, createdAt: daysAgo(7) }, now)).toBe(7)
+  })
+
+  it('archives after the period without activity, and a new message brings it back', () => {
+    expect(isArchived({ lastMessageAt: daysAgo(60) }, now, 60)).toBe(true)
+    expect(isArchived({ lastMessageAt: daysAgo(59) }, now, 60)).toBe(false)
+    expect(isArchived({ lastMessageAt: daysAgo(400) }, now, null)).toBe(false)
+  })
+})
+
+describe('what the list suggests clearing', () => {
+  it('suggests only my own conversations', () => {
+    expect(cleanupReason({ mine: false, lastMessageAt: null, createdAt: daysAgo(5) }, now)).toBeNull()
+  })
+
+  it('an empty one, and one idle for 30 days', () => {
+    expect(cleanupReason({ mine: true, lastMessageAt: null, createdAt: daysAgo(0) }, now)).toBe('empty')
+    expect(cleanupReason({ mine: true, lastMessageAt: daysAgo(30) }, now)).toBe('inactive')
+    expect(cleanupReason({ mine: true, lastMessageAt: daysAgo(29) }, now)).toBeNull()
+  })
+})
+
+describe('the empty conversations the daily job removes', () => {
+  const empty = { lastMessageAt: null, messages: 0, createdAt: daysAgo(2), lastTouchedAt: daysAgo(2) }
+
+  it('removes one never asked anything and not opened for a day', () => {
+    expect(emptyAndAbandoned(empty, now)).toBe(true)
+  })
+
+  it('keeps one with any message, even when the activity column was never written', () => {
+    expect(emptyAndAbandoned({ ...empty, messages: 1 }, now)).toBe(false)
+    expect(emptyAndAbandoned({ ...empty, lastMessageAt: daysAgo(2) }, now)).toBe(false)
+  })
+
+  it('keeps one started today, or opened today', () => {
+    expect(emptyAndAbandoned({ ...empty, createdAt: daysAgo(0) }, now)).toBe(false)
+    expect(emptyAndAbandoned({ ...empty, lastTouchedAt: daysAgo(0) }, now)).toBe(false)
+  })
+})
+
+describe('what the list stands on', () => {
+  const rows = [
+    { id: 'live' },
+    { id: 'old', archived: true },
+    { id: 'hid', hidden: true },
+    { id: 'empty', cleanupReason: 'empty', hidden: true },
+    { id: 'idle', cleanupReason: 'inactive', archived: true }
+  ]
+  const ids = (opts = {}) => listedEntries(rows, opts).map(row => row.id)
+
+  it('leaves the archived and the hidden out by default', () => {
+    expect(ids()).toEqual(['live'])
+  })
+
+  it('shows the archived when asked, or when searching', () => {
+    expect(ids({ includeArchived: true })).toEqual(['live', 'old', 'idle'])
+    expect(ids({ search: 'x' })).toEqual(['live', 'old', 'idle'])
+    expect(ids({ search: '  ' })).toEqual(['live'])
+  })
+
+  it('the suggestions are every candidate, hidden or archived', () => {
+    expect(ids({ cleanupOnly: true })).toEqual(['empty', 'idle'])
+  })
+})

package/server/service/chat-session/session-cleanup.ts

@@ -0,0 +1,69 @@
+/*
+ * Keeping the conversation list short - pure, tested alone (design/ai/shared-dock.md §2-7).
+ *
+ * 2026-10-25, the user: 「AI 세션관리를 좀 더 편리하게」 - many at once, suggestions of what to clear, a period after the
+ * last update. Three rules come out of it:
+ *
+ *   archived   No activity for `sessionArchiveDays` (default 60): the list leaves it out until asked
+ *              (「보관 포함」) or searched. Nothing is written - a new message brings it back by itself.
+ *              Archiving deletes nothing: a conversation holds the cards it offered and what came of them.
+ *   candidate  What the list suggests clearing, only among the caller's own (only the creator deletes):
+ *              `empty` - no message ever; `inactive` - no activity for INACTIVE_DAYS.
+ *   empty      A conversation that never got a message and that nobody opened for EMPTY_DAYS is removed by the
+ *              daily job - there is nothing in it to keep.
+ */
+import { DAY_MS } from './session-retention.js'
+
+export const DEFAULT_ARCHIVE_DAYS = 60
+/** A conversation of mine is suggested for clearing after this many days without activity. */
+export const INACTIVE_DAYS = 30
+/** An empty conversation nobody touched for this long is removed. */
+export const EMPTY_DAYS = 1
+
+export type CleanupReason = 'empty' | 'inactive'
+
+interface Activity {
+  lastMessageAt?: Date | string | null
+  createdAt?: Date | string | null
+}
+
+function time(value: Date | string | null | undefined): number {
+  if (!value) return 0
+  const at = value instanceof Date ? value.getTime() : Date.parse(value)
+  return Number.isFinite(at) ? at : 0
+}
+
+/** The archive period the config asks for: a positive number of days, `null` when archiving is off, the default otherwise. */
+export function archiveDaysOf(value: unknown): number | null {
+  if (value === false || value === 0 || value === '0') return null
+  const days = Number(value)
+  return Number.isFinite(days) && days > 0 ? days : DEFAULT_ARCHIVE_DAYS
+}
+
+/** Whole days since the conversation last moved - its last message, or its start when it has none. */
+export function idleDays(session: Activity, now: Date): number {
+  const last = time(session.lastMessageAt) || time(session.createdAt)
+  return last ? Math.floor((now.getTime() - last) / DAY_MS) : 0
+}
+
+export function isArchived(session: Activity, now: Date, archiveDays: number | null): boolean {
+  return archiveDays !== null && idleDays(session, now) >= archiveDays
+}
+
+/** Why the list suggests clearing this conversation, or `null`. Only one the caller started - only the creator deletes. */
+export function cleanupReason(session: Activity & { mine?: boolean }, now: Date): CleanupReason | null {
+  if (!session.mine) return null
+  if (!time(session.lastMessageAt)) return 'empty'
+  return idleDays(session, now) >= INACTIVE_DAYS ? 'inactive' : null
+}
+
+/**
+ * Whether the daily job removes an empty conversation: no message, started more than EMPTY_DAYS ago, and no seat in it
+ * touched since (opening a conversation marks its reader's seat). A dock holding it open the same day keeps it.
+ */
+export function emptyAndAbandoned(session: Activity & { messages: number; lastTouchedAt?: Date | string | null }, now: Date): boolean {
+  if (session.messages > 0 || time(session.lastMessageAt)) return false
+  const cutoff = now.getTime() - EMPTY_DAYS * DAY_MS
+  const started = time(session.createdAt)
+  return !!started && started < cutoff && time(session.lastTouchedAt) < cutoff
+}

package/server/service/chat-session/session-inbox.ts

@@ -171,6 +171,19 @@ export function filterInbox<T extends InboxEntry & { mine?: boolean }>(entries:
   })
 }
 
+/**
+ * Which entries the list stands on before its filters (shared-dock.md §2-7): the suggestions to clear are every
+ * candidate, hidden or archived; otherwise a hidden one waits for its filter, and an archived one for its filter or a
+ * search - finding an old conversation by a word is how it is mostly looked for.
+ */
+export function listedEntries<T extends { hidden?: boolean; archived?: boolean; cleanupReason?: string | null }>(
+  entries: T[],
+  opts: { showHidden?: boolean | null; includeArchived?: boolean | null; cleanupOnly?: boolean | null; search?: string | null } = {}
+): T[] {
+  if (opts.cleanupOnly) return entries.filter(entry => entry.cleanupReason)
+  return entries.filter(entry => (opts.showHidden || !entry.hidden) && (opts.includeArchived || !!opts.search?.trim() || !entry.archived))
+}
+
 export function searchInbox(entries: InboxEntry[], search?: string): InboxEntry[] {
   const q = (search ?? '').trim().toLowerCase()
   if (!q) return entries

package/server/service/chat-session/session-purge.ts

@@ -8,6 +8,9 @@
  * files together once the retention period has passed.
  *
  * Retention: config `ai-assistant.sessionRetentionDays`, default 30. `0` or `false` turns the job off.
+ *
+ * The same run removes empty conversations nobody opened for a day (`session-cleanup.ts`, shared-dock.md §2-7) -
+ * 「새 대화」 starts a row before its first question, and one never asked stays in the list otherwise.
  */
 import { config } from '@things-factory/env'
 import { getRepository } from '@things-factory/shell'
@@ -19,6 +22,7 @@ import { ChatSession } from './chat-session.js'
 import { removeSessionFiles } from './session-attachments.js'
 
 import { DAY_MS, purgeCutoff, retentionDaysOf } from './session-retention.js'
+import { EMPTY_DAYS, emptyAndAbandoned } from './session-cleanup.js'
 
 export { DEFAULT_RETENTION_DAYS, purgeCutoff, retentionDaysOf } from './session-retention.js'
 /** How many conversations one run empties - a large backlog is worked off over several runs. */
@@ -26,12 +30,48 @@ export const PURGE_BATCH = 100
 
 export interface PurgeResult {
   purged: number
+  /** Empty conversations removed - never asked anything, and nobody opened them for a day. */
+  emptied: number
   failed: { sessionId: string; message: string }[]
 }
 
+/** A conversation, its messages, its participants and its files, gone together. */
+async function removeConversation(session: ChatSession): Promise<void> {
+  await removeSessionFiles(session as any)
+  /* Messages point at each other (parentMessage) - drop the links before the rows. */
+  await getRepository(ChatMessage).update({ session: { id: session.id }, parentMessage: Not(IsNull()) } as any, { parentMessage: null } as any)
+  await getRepository(ChatMessage).delete({ session: { id: session.id } } as any)
+  await getRepository(ChatSessionParticipant).delete({ session: { id: session.id } } as any)
+  /* Board patches and anything else hanging on the session go with it (ON DELETE CASCADE). */
+  await getRepository(ChatSession).delete({ id: In([session.id]) } as any)
+}
+
+/** Removes the empty conversations nobody opened for EMPTY_DAYS. Each is checked against its messages and seats, not the denormalized activity alone. */
+export async function removeEmptySessions(now = new Date(), result: PurgeResult = { purged: 0, emptied: 0, failed: [] }): Promise<PurgeResult> {
+  const sessions = await getRepository(ChatSession).find({
+    where: { lastMessageAt: IsNull(), createdAt: LessThan(new Date(now.getTime() - EMPTY_DAYS * DAY_MS)) } as any,
+    relations: ['domain'],
+    take: PURGE_BATCH
+  })
+  for (const session of sessions) {
+    try {
+      const messages = await getRepository(ChatMessage).count({ where: { session: { id: session.id } } as any })
+      const seats = await getRepository(ChatSessionParticipant).find({ where: { session: { id: session.id } } as any, withDeleted: true })
+      const touched = seats.flatMap(seat => [seat.updatedAt, seat.lastReadAt]).filter(Boolean) as Date[]
+      const lastTouchedAt = touched.length ? new Date(Math.max(...touched.map(at => new Date(at).getTime()))) : null
+      if (!emptyAndAbandoned({ ...(session as any), messages, lastTouchedAt }, now)) continue
+      await removeConversation(session)
+      result.emptied++
+    } catch (error) {
+      result.failed.push({ sessionId: session.id!, message: (error as Error).message })
+    }
+  }
+  return result
+}
+
 /** Empties the conversations whose deletion is older than the retention period. */
 export async function purgeDeletedSessions(now = new Date(), retentionDays = retentionDaysOf(config.get('ai-assistant', {})?.sessionRetentionDays)): Promise<PurgeResult> {
-  const result: PurgeResult = { purged: 0, failed: [] }
+  const result: PurgeResult = { purged: 0, emptied: 0, failed: [] }
   if (retentionDays === null) return result
 
   const sessions = await getRepository(ChatSession).find({
@@ -43,13 +83,7 @@ export async function purgeDeletedSessions(now = new Date(), retentionDays = ret
 
   for (const session of sessions) {
     try {
-      await removeSessionFiles(session as any)
-      /* Messages point at each other (parentMessage) - drop the links before the rows. */
-      await getRepository(ChatMessage).update({ session: { id: session.id }, parentMessage: Not(IsNull()) } as any, { parentMessage: null } as any)
-      await getRepository(ChatMessage).delete({ session: { id: session.id } } as any)
-      await getRepository(ChatSessionParticipant).delete({ session: { id: session.id } } as any)
-      /* Board patches and anything else hanging on the session go with it (ON DELETE CASCADE). */
-      await getRepository(ChatSession).delete({ id: In([session.id]) } as any)
+      await removeConversation(session)
       result.purged++
     } catch (error) {
       /* One conversation that cannot be emptied must not stop the rest; it is tried again next run. */
@@ -67,8 +101,10 @@ export function schedulePurge(): void {
   if (timer) return
   const run = () =>
     purgeDeletedSessions()
-      .then(({ purged, failed }) => {
-        if (purged || failed.length) console.info(`[ai-assistant] purged ${purged} deleted conversation(s)`, failed.length ? { failed } : '')
+      .then(result => removeEmptySessions(new Date(), result))
+      .then(({ purged, emptied, failed }) => {
+        if (purged || emptied || failed.length)
+          console.info(`[ai-assistant] purged ${purged} deleted and ${emptied} empty conversation(s)`, failed.length ? { failed } : '')
       })
       .catch(error => console.warn('[ai-assistant] purging deleted conversations failed:', (error as Error).message))