@things-factory/ai-assistant 10.1.46 → 10.1.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.46",
+  "version": "10.1.50",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -26,16 +26,23 @@
   },
   "dependencies": {
     "@apollo/client": "^3.13.0",
+    "@material/web": "^2.0.0",
     "@operato/graphql": "^10.0.0",
     "@operato/i18n": "^10.0.0",
+    "@operato/layout": "^10.0.0",
+    "@operato/popup": "^10.16.0",
+    "@operato/shell": "^10.0.0",
     "@operato/styles": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.39",
-    "@things-factory/auth-base": "^10.1.46",
+    "@things-factory/apptool-base": "^10.1.47",
+    "@things-factory/attachment-base": "^10.1.47",
+    "@things-factory/auth-base": "^10.1.47",
     "@things-factory/env": "^10.1.20",
-    "@things-factory/shell": "^10.1.46",
+    "@things-factory/shell": "^10.1.47",
     "dompurify": "^3.0.0",
     "graphql-scalars": "^1.22.0",
     "graphql-tag": "^2.12.6",
+    "graphql-upload": "^15.0.2",
     "lit": "^3.1.2",
     "marked": "^15.0.0"
   },
@@ -44,5 +51,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "d3467cde550453f3348fed0ed6c79a12a6ba0db4"
+  "gitHead": "4700d39d70eb5fae4ad56cf47ea0b966c8516ae2"
 }

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

@@ -53,6 +53,11 @@ import { judgeSessionKind } from './chat-session/session-kind.js'
 import { readerGate } from './chat-message/reader-gate.js'
 import { inviteMentionedUsers } from './chat-session-participant/mention-invite.js'
 import { buildInviteNotification } from './chat-session-participant/invite-notification.js'
+import { isSessionParticipant } from './chat-session-participant/participant-lookup.js'
+import { assertMayWriteSession } from './chat-session/session-write-gate.js'
+import { attachmentHistoryLine, refuseAttachments } from './chat-session/attachment-policy.js'
+import { attachmentForModel, describeAttachment, findChatAttachment } from './chat-session/session-attachments.js'
+import { getAssistantMode } from './assistant-mode/registry.js'
 import { resolveModeSettings } from './assistant-mode/resolve.js'
 import { requestTranslator } from './request-translator.js'
 
@@ -121,6 +126,12 @@ class AssistantChatInput {
   })
   truncateAfterMessageId?: string
 
+  @Field(() => [String], {
+    nullable: true,
+    description: 'Files stored with this conversation by attachToConversation, sent with this turn.'
+  })
+  attachmentIds?: string[]
+
 }
 
 @ObjectType()
@@ -225,6 +236,16 @@ export class AssistantChatResolver {
     if (input.sessionId) {
       const found = await sessionRepo.findOneBy({ id: input.sessionId, domain: { id: domain.id } as any })
       if (!found) throw new Error(`ChatSession ${input.sessionId} not found`)
+      /*
+       * A private conversation is written by its people only - and here more than anywhere: the answer is
+       * built on this conversation's history, so an outsider's question would read it back to them.
+       */
+      await assertMayWriteSession({
+        session: found as any,
+        userId: user?.id,
+        isParticipant: () => isSessionParticipant(domain.id, found.id!, user?.id),
+        t: (key, options) => t(key, options as any)
+      })
       if (found.anchorType === 'figure' && input.hostContext?.figureId !== found.anchorId) {
         throw new Error(
           context.t('ai-assistant.text.other-figure-history', {
@@ -265,6 +286,26 @@ export class AssistantChatResolver {
     const lastUserMessage = input.messages[input.messages.length - 1]
     let userMessageId: string | undefined
 
+    /*
+     * Files sent with this turn (design/ai/shared-dock.md §9). They were stored with this conversation by
+     * attachToConversation; one that is not this conversation's is refused, never read. The policy is the
+     * mode's - checked again here, since the door is the authority, not the screen.
+     */
+    const attachmentRows: any[] = []
+    if (input.attachmentIds?.length) {
+      if (!session) throw new Error(t('ai-assistant.text.attachments-need-session', { defaultValue: 'attachments need a saved conversation.' }))
+      for (const id of input.attachmentIds) {
+        const row = await findChatAttachment(domain.id, session.id!, id)
+        if (!row) throw new Error(t('ai-assistant.text.attachment-not-in-session', { defaultValue: 'an attachment does not belong to this conversation.' }))
+        attachmentRows.push(row)
+      }
+      const refusal = refuseAttachments(
+        getAssistantMode(input.mode.kind)?.attachments,
+        attachmentRows.map(row => ({ name: row.name, type: row.mimetype, size: Number(row.size) }))
+      )
+      if (refusal) throw new Error(t(`ai-assistant.text.${refusal.code}`, { ...(refusal as any), defaultValue: refusal.code }))
+    }
+
     if (session && lastUserMessage?.role === 'user') {
       const previousLast = await messageRepo.findOne({
         where: { session: { id: session.id } as any },
@@ -280,10 +321,11 @@ export class AssistantChatResolver {
          * from the request — two sources for one fact can disagree.
          */
         addressee: 'assistant',
+        attachments: attachmentRows.length ? JSON.stringify(attachmentRows.map(describeAttachment)) : undefined,
         creator: user,
         updater: user,
         parentMessage: previousLast ? ({ id: previousLast.id } as any) : undefined
-      })
+      } as any)
       userMessageId = saved.id
 
       /*
@@ -312,7 +354,7 @@ export class AssistantChatResolver {
         visibility: (session as any).visibility
       })
       if (invite.invited.length > 0) {
-        const payload = buildInviteNotification(invite.invited, undefined, user)
+        const payload = buildInviteNotification(invite.invited, undefined, user, (session as any)?.name)
         try {
           if (payload) await (context.state as any)?.notify?.(payload)
         } catch {
@@ -373,7 +415,14 @@ export class AssistantChatResolver {
           storedRows.map(message => ({
             id: message.id,
             role: message.role,
-            content: message.content,
+            /*
+             * A file sent in an earlier turn is not sent again - one line names it, and the model opens it
+             * with readChatAttachment when it needs to (cost is a usage axis, ADR-0061 decision 6).
+             */
+            content:
+              message.id !== userMessageId && (message as any).attachmentsJson?.length
+                ? [message.content, ...(message as any).attachmentsJson.map(attachmentHistoryLine)].join('\n')
+                : message.content,
             senderId: (message as any).creator?.id,
             senderName: (message as any).creator?.name,
             addressee: (message as any).addressee
@@ -390,7 +439,25 @@ export class AssistantChatResolver {
         )
       : input.messages.map(message => ({ role: message.role as any, content: message.content }))
 
-    if (input.hostContext?.image?.data && conversation.length > 0) {
+    if (attachmentRows.length && conversation.length > 0) {
+      const last = conversation[conversation.length - 1]
+      if (last.role === 'user' && typeof last.content === 'string') {
+        const parts: any[] = [{ type: 'text', text: last.content }]
+        for (const row of attachmentRows) {
+          const file = await attachmentForModel(row)
+          if (file.type === 'image') {
+            parts.push({ type: 'image', source: { kind: 'base64', data: file.data, mediaType: file.mediaType } })
+          } else {
+            parts.push({
+              type: 'text',
+              text: `[attachment ${row.id}: ${file.name}${file.truncated ? ' - cut, the file is longer' : ''}]\n${file.text}`
+            })
+          }
+        }
+        last.content = parts as any
+      }
+    } else if (input.hostContext?.image?.data && conversation.length > 0) {
+      /* The screen-image path (figure's rendered view) - not a file of the conversation. */
       const last = conversation[conversation.length - 1]
       if (last.role === 'user' && typeof last.content === 'string') {
         const raw = input.hostContext.image
@@ -493,7 +560,7 @@ export class AssistantChatResolver {
         domainId: domain.id,
         client,
         maxTurns: LLM_HISTORY_MAX_TURNS,
-        locale: context.state?.locale
+        locale: context.state?.lng
       })
     }
 

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

@@ -55,6 +55,12 @@ class AssistantModeView {
 
   @Field({ nullable: true, description: 'The line shown once the host reports a proposal staged.' })
   stagedNotice?: string
+
+  @Field(() => GraphQLJSON, {
+    nullable: true,
+    description: "What this conversation accepts as attachments: { kinds: ('image'|'text')[], maxBytes, maxFiles }. Null: none."
+  })
+  attachments?: any
 }
 
 @ObjectType({ description: 'A conversation a screen may open for what it is showing.' })

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

@@ -1,3 +1,4 @@
+import type { AttachmentPolicy } from '../chat-session/attachment-policy.js'
 /**
  * What the door and the screen each take from a mode.
  *
@@ -51,7 +52,10 @@ export function resolveModeSettings(ref: AssistantModeRef, t: Translate): ModeSe
 
   return {
     systemPrompt: mode.systemPrompt,
-    toolCategories: mode.toolCategories,
+    /* A mode that takes attachments can open the files sent in earlier turns (design/ai/shared-dock.md §9-4). */
+    toolCategories: mode.attachments?.kinds?.length
+      ? [...(mode.toolCategories ?? []), 'chat-attachments']
+      : mode.toolCategories,
     requireToolOnFirstTurn: mode.requireToolOnFirstTurn,
     model: mode.model,
     temperature: mode.temperature,
@@ -77,6 +81,8 @@ export interface AssistantModeView {
   examples?: Array<{ label: string; items: string[] }>
   footerNotice?: string
   stagedNotice?: string
+  /** What the screen may attach - the same policy the server enforces. */
+  attachments?: AttachmentPolicy
 }
 
 /** What the screen shows, in the words of the request's locale. */
@@ -100,6 +106,7 @@ export function assistantModeView(kind: string, t: Translate): AssistantModeView
       items: group.itemKeys.map(key => t(key))
     })),
     footerNotice: mode.footerNoticeKey ? t(mode.footerNoticeKey) : undefined,
-    stagedNotice: mode.stagedNoticeKey ? t(mode.stagedNoticeKey) : undefined
+    stagedNotice: mode.stagedNoticeKey ? t(mode.stagedNoticeKey) : undefined,
+    attachments: mode.attachments
   }
 }

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

@@ -1,3 +1,4 @@
+import type { AttachmentPolicy } from '../chat-session/attachment-policy.js'
 /**
  * What a conversation is, declared by the app server that owns the screen (ADR-0061 decision 7).
  *
@@ -94,6 +95,11 @@ export interface AssistantModeSpec {
    */
   exampleKeys?: Array<{ labelKey: string; itemKeys: string[] }>
 
+  /**
+   * What this conversation accepts as attachments (design/ai/shared-dock.md §9-1). Absent: nothing - the
+   * screen offers no attach button, so no file is taken that the model would never see.
+   */
+  attachments?: AttachmentPolicy
   /** 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-message/chat-message.ts

@@ -160,6 +160,23 @@ export class ChatMessage {
    *
    * 형태: string[] 를 JSON-stringify. 비었으면 null(= 접지 정상).
    */
+  /**
+   * The files sent with this turn - `[{ id, name, mimetype, size }]` as JSON (design/ai/shared-dock.md §9-2).
+   * The files themselves live in attachment-base under the conversation and are opened only through it.
+   */
+  @Column({ type: 'text', nullable: true })
+  attachments?: string
+
+  @Field(() => GraphQLJSON, { nullable: true, description: 'Files sent with this turn: [{ id, name, mimetype, size }].' })
+  get attachmentsJson(): any {
+    if (!this.attachments) return null
+    try {
+      return JSON.parse(this.attachments)
+    } catch {
+      return null
+    }
+  }
+
   @Column({ type: 'varchar', length: 1024, nullable: true })
   groundingWarnings?: string
 

package/server/service/chat-message/fold-session-history.test.ts

@@ -96,3 +96,21 @@ describe('rowsAfterWatermark', () => {
     expect(where[1]).toMatchObject({ session: { id: 's1' }, createdAt: at })
   })
 })
+
+/*
+ * The summary is written in the conversation's language only if the language reaches it. The i18n
+ * middleware leaves it on `ctx.state.lng` (`i18n-base` koa-i18next `setLanguage`); nothing sets
+ * `state.locale`. The door read `state.locale`, so every summary was asked for with no language and
+ * a Korean deliberation could be summarised in English (found 2026-09-24).
+ */
+describe('the door hands the fold the request language', () => {
+  it('★ reads state.lng — the key the i18n middleware sets', () => {
+    const { readFileSync } = require('fs')
+    const { join } = require('path')
+    const resolver: string = readFileSync(join(__dirname, '..', 'assistant-chat-resolver.ts'), 'utf8')
+    const call = resolver.slice(resolver.indexOf('void foldSessionHistory({'), resolver.indexOf('})', resolver.indexOf('void foldSessionHistory({')))
+
+    expect(call).toMatch(/locale: context\.state\?\.lng\b/)
+    expect(resolver).not.toMatch(/state\?\.locale\b/)
+  })
+})

package/server/service/chat-session/attachment-policy.test.ts

@@ -0,0 +1,42 @@
+/* What a conversation accepts as attachments - design/ai/shared-dock.md §9-1. */
+import { attachmentHistoryLine, attachmentKindOf, refuseAttachments } from './attachment-policy'
+
+describe('attachment policy', () => {
+  const policy = { kinds: ['image', 'text'] as any, maxBytes: 1000, maxFiles: 2 }
+
+  it('a mode that declares nothing takes nothing - no file the model would never see', () => {
+    expect(refuseAttachments(undefined, [{ name: 'a.png', type: 'image/png', size: 1 }])).toEqual({ code: 'attachments-not-accepted' })
+    expect(refuseAttachments({ kinds: [] }, [{ name: 'a.png', type: 'image/png' }])).toEqual({ code: 'attachments-not-accepted' })
+  })
+
+  it('no files is no refusal', () => {
+    expect(refuseAttachments(undefined, [])).toBeNull()
+  })
+
+  it('kinds come from the type, or the name when the browser did not know the type', () => {
+    expect(attachmentKindOf({ type: 'image/jpeg' })).toBe('image')
+    expect(attachmentKindOf({ type: 'text/csv' })).toBe('text')
+    expect(attachmentKindOf({ type: '', name: 'report.CSV' })).toBe('text')
+    expect(attachmentKindOf({ type: 'application/pdf', name: 'a.pdf' })).toBeNull()
+  })
+
+  it('each limit refuses by name, before sending', () => {
+    expect(refuseAttachments(policy, [{ name: 'a.pdf', type: 'application/pdf', size: 1 }])).toMatchObject({ code: 'attachment-kind-not-accepted', name: 'a.pdf' })
+    expect(refuseAttachments(policy, [{ name: 'big.png', type: 'image/png', size: 1001 }])).toMatchObject({ code: 'attachment-too-large', name: 'big.png', maxBytes: 1000 })
+    expect(refuseAttachments(policy, [{}, {}, {}] as any)).toEqual({ code: 'too-many-attachments', maxFiles: 2 })
+  })
+
+  it('a kind outside the declared ones is refused', () => {
+    expect(refuseAttachments({ kinds: ['image'] }, [{ name: 'a.csv', type: 'text/csv', size: 1 }])).toMatchObject({ code: 'attachment-kind-not-accepted' })
+  })
+
+  it('files within the policy go', () => {
+    expect(refuseAttachments(policy, [{ name: 'a.png', type: 'image/png', size: 10 }, { name: 'b.csv', type: 'text/csv', size: 10 }])).toBeNull()
+  })
+
+  it('the line an earlier turn keeps names the file and how to open it', () => {
+    expect(attachmentHistoryLine({ id: 'f1', name: 'press.csv', mimetype: 'text/csv', size: 120 })).toBe(
+      '[attachment f1: press.csv (text/csv, 120 bytes) - readChatAttachment to open it]'
+    )
+  })
+})

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

@@ -0,0 +1,68 @@
+/*
+ * What a conversation accepts as attachments - declared by its mode (design/ai/shared-dock.md §9-1).
+ *
+ * Pure, so the rule is tested alone and the screen can say "no" before anything is sent. A mode that
+ * declares nothing accepts nothing: the chat once took .csv and .json, carried them, and no code ever
+ * showed them to the model - the person got an answer about a file it had never seen (AI standard §7).
+ */
+
+export type AttachmentKind = 'image' | 'text'
+
+export interface AttachmentPolicy {
+  kinds: AttachmentKind[]
+  /** Per file. */
+  maxBytes?: number
+  /** Per message. */
+  maxFiles?: number
+}
+
+export const DEFAULT_MAX_BYTES = 5 * 1024 * 1024
+export const DEFAULT_MAX_FILES = 5
+/** How much of a text file reaches the model in the turn it was sent. */
+export const TEXT_CHARS_FOR_MODEL = 20_000
+
+const TEXT_TYPES = ['text/plain', 'text/csv', 'text/markdown', 'application/json']
+const TEXT_EXTENSIONS = ['.txt', '.csv', '.md', '.json']
+
+/** Which kind a file is, from its type - and its name when the browser did not know the type. */
+export function attachmentKindOf(file: { type?: string; name?: string }): AttachmentKind | null {
+  const type = (file.type || '').toLowerCase()
+  if (type.startsWith('image/')) return 'image'
+  if (TEXT_TYPES.includes(type)) return 'text'
+  const name = (file.name || '').toLowerCase()
+  if (TEXT_EXTENSIONS.some(ext => name.endsWith(ext))) return 'text'
+  return null
+}
+
+export type AttachmentRefusal =
+  | { code: 'attachments-not-accepted' }
+  | { code: 'attachment-kind-not-accepted'; name: string; kinds: AttachmentKind[] }
+  | { code: 'attachment-too-large'; name: string; maxBytes: number }
+  | { code: 'too-many-attachments'; maxFiles: number }
+
+/** `null` when every file may go; otherwise the first reason, by name - said before sending, never cut silently. */
+export function refuseAttachments(
+  policy: AttachmentPolicy | null | undefined,
+  files: { name?: string; type?: string; size?: number }[]
+): AttachmentRefusal | null {
+  if (!files.length) return null
+  if (!policy || !policy.kinds?.length) return { code: 'attachments-not-accepted' }
+
+  const maxFiles = policy.maxFiles ?? DEFAULT_MAX_FILES
+  if (files.length > maxFiles) return { code: 'too-many-attachments', maxFiles }
+
+  const maxBytes = policy.maxBytes ?? DEFAULT_MAX_BYTES
+  for (const file of files) {
+    const kind = attachmentKindOf(file)
+    if (!kind || !policy.kinds.includes(kind)) {
+      return { code: 'attachment-kind-not-accepted', name: file.name || '', kinds: policy.kinds }
+    }
+    if ((file.size ?? 0) > maxBytes) return { code: 'attachment-too-large', name: file.name || '', maxBytes }
+  }
+  return null
+}
+
+/** The line history keeps for a file once its turn is past - the model reads the file again only by asking. */
+export function attachmentHistoryLine(file: { id: string; name?: string; mimetype?: string; size?: number | string }): string {
+  return `[attachment ${file.id}: ${file.name || 'unnamed'} (${file.mimetype || 'unknown type'}, ${file.size ?? '?'} bytes) - readChatAttachment to open it]`
+}

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

@@ -0,0 +1,45 @@
+/*
+ * Where a person opens a conversation's file - GET /chat-attachments/:sessionId/:attachmentId.
+ *
+ * Domain-private (sign-in and tenancy required), and the conversation's own read gate on top: a private
+ * conversation's file opens for its participants only, a deleted conversation's for nobody (design/ai/
+ * shared-dock.md §9-3). attachment-base's own route is public and unauthenticated, so chat files are
+ * never linked through it. `private` caching - a shared cache must not keep a private conversation's file.
+ */
+import { STORAGE } from '@things-factory/attachment-base'
+import { getRepository } from '@things-factory/shell'
+
+import { ChatSession } from './chat-session.js'
+import { mayReadSession } from './session-visibility.js'
+import { findChatAttachment } from './session-attachments.js'
+import { isSessionParticipant } from '../chat-session-participant/participant-lookup.js'
+
+export const CHAT_ATTACHMENT_ROUTE = 'chat-attachments'
+
+/** The address a screen uses for one file of a conversation. */
+export function chatAttachmentUrl(sessionId: string, attachmentId: string): string {
+  return `/${CHAT_ATTACHMENT_ROUTE}/${encodeURIComponent(sessionId)}/${encodeURIComponent(attachmentId)}`
+}
+
+process.on('bootstrap-module-domain-private-route' as any, (_app: any, routes: any) => {
+  routes.get(`/${CHAT_ATTACHMENT_ROUTE}/:sessionId/:attachmentId`, async (context: any, next: any) => {
+    const { domain, user } = context.state
+    const { sessionId, attachmentId } = context.params
+
+    /* A soft-deleted conversation is not found here - its files close with it (§9-5). */
+    const session: any = await getRepository(ChatSession).findOne({ where: { id: sessionId, domain: { id: domain.id } } as any })
+    const readable = !!session && mayReadSession(session.visibility, await isSessionParticipant(domain.id, sessionId, user?.id))
+    const row: any = readable ? await findChatAttachment(domain.id, sessionId, attachmentId) : undefined
+
+    if (!row) {
+      /* One answer for "none", "not yours" and "deleted" - telling them apart would say what exists. */
+      context.status = 404
+      return
+    }
+
+    context.set('Cache-Control', 'private, max-age=3600')
+    context.set('Content-Disposition', `inline; filename*=UTF-8''${encodeURIComponent(row.name)}`)
+    if (row.mimetype) context.type = row.mimetype
+    await STORAGE.sendFile(context, row.path, next)
+  })
+})

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

@@ -0,0 +1,63 @@
+/*
+ * 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
+ * belongs to - the same gate as reading its messages (ADR-0073 decision 1) - so a file id from elsewhere
+ * opens nothing.
+ *
+ * The category is opened for every mode that declares an attachment policy (resolve.ts).
+ */
+import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
+import { Attachment } from '@things-factory/attachment-base'
+import { getRepository } from '@things-factory/shell'
+
+import { ChatSession } from './chat-session.js'
+import { mayReadSession } from './session-visibility.js'
+import { isSessionParticipant } from '../chat-session-participant/participant-lookup.js'
+import { attachmentForModel, CHAT_ATTACHMENT_REF } from './session-attachments.js'
+
+export const CHAT_ATTACHMENT_CATEGORY = 'chat-attachments'
+
+const readChatAttachment: ToolSpec = {
+  kind: 'read',
+  name: 'readChatAttachment',
+  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).',
+  schema: {
+    type: 'object',
+    properties: { attachmentId: { type: 'string', description: 'The id from the "[attachment <id>: ...]" line.' } },
+    required: ['attachmentId']
+  },
+  builder: async (args: any, context: any) => {
+    const { domain, user } = context?.state ?? {}
+    const id = typeof args?.attachmentId === 'string' ? args.attachmentId.trim() : ''
+    if (!domain?.id || !id) return { absent: 'no-attachment', message: 'no attachment id was given.' }
+
+    const row: any = await getRepository(Attachment).findOne({ where: { id, domain: { id: domain.id }, refType: CHAT_ATTACHMENT_REF } as any })
+    const session: any = row && (await getRepository(ChatSession).findOne({ where: { id: row.refBy, domain: { id: domain.id } } as any }))
+    if (!row || !session) return { absent: 'not-found', attachmentId: id, message: 'there is no such attachment in a conversation here.' }
+
+    const participant = await isSessionParticipant(domain.id, session.id, user?.id)
+    if (!mayReadSession(session.visibility, participant)) {
+      /* Same answer as absent - saying "it exists but is private" would itself leak. */
+      return { absent: 'not-found', attachmentId: id, message: 'there is no such attachment in a conversation here.' }
+    }
+
+    const file = await attachmentForModel(row)
+    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.' } : {}) }
+  }
+} as ToolSpec
+
+export const chatAttachmentCategory: ToolCategory = {
+  name: CHAT_ATTACHMENT_CATEGORY,
+  guidance:
+    '- A line "[attachment <id>: <name> ...]" names a file sent in an earlier turn. Call readChatAttachment with that id before answering about its contents; never guess what a file says.',
+  specs: [readChatAttachment]
+}
+
+registerToolCategory(chatAttachmentCategory)

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

@@ -0,0 +1,89 @@
+/*
+ * A conversation's files - stored in attachment-base, opened only through the conversation.
+ *
+ * Files are kept with `refType: 'chat-session'`, `refBy: <session id>` (design/ai/shared-dock.md §9-2).
+ * They are never handed out through attachment-base's own route: that route is public and unauthenticated
+ * (routes.ts, "TODO make this secure"), so a private conversation's file would leave the conversation.
+ * Every read here passes the conversation's gate first (§9-3); this module only does the storage part.
+ */
+import { Attachment, STORAGE, createAttachment } from '@things-factory/attachment-base'
+import { getRepository } from '@things-factory/shell'
+
+import { attachmentKindOf, TEXT_CHARS_FOR_MODEL } from './attachment-policy.js'
+
+export const CHAT_ATTACHMENT_REF = 'chat-session'
+
+export interface StoredChatAttachment {
+  id: string
+  name: string
+  mimetype: string
+  size: number
+}
+
+export function describeAttachment(row: any): StoredChatAttachment {
+  return { id: row.id, name: row.name, mimetype: row.mimetype, size: Number(row.size) || 0 }
+}
+
+/** Stores uploaded files under the conversation. The caller has passed the write gate and the mode's policy. */
+export async function saveChatAttachments(sessionId: string, files: any[], context: any): Promise<StoredChatAttachment[]> {
+  const saved: StoredChatAttachment[] = []
+  for (const file of files) {
+    const row = await createAttachment(null, { attachment: { file, category: 'chat', refType: CHAT_ATTACHMENT_REF, refBy: sessionId } }, context)
+    saved.push(describeAttachment(row))
+  }
+  return saved
+}
+
+/** One file of the conversation - `undefined` when it is not this conversation's. */
+export async function findChatAttachment(domainId: string, sessionId: string, attachmentId: string): Promise<any | undefined> {
+  return (
+    (await getRepository(Attachment).findOne({
+      where: { id: attachmentId, domain: { id: domainId }, refType: CHAT_ATTACHMENT_REF, refBy: sessionId } as any
+    })) ?? undefined
+  )
+}
+
+/**
+ * What the model gets for a file: an image as bytes, a text file as its text (cut at TEXT_CHARS_FOR_MODEL,
+ * and the cut is said), anything else as a line that names it.
+ */
+export async function attachmentForModel(row: any): Promise<
+  | { type: 'image'; data: Buffer; mediaType: string; name: string }
+  | { type: 'text'; text: string; name: string; truncated: boolean }
+> {
+  const kind = attachmentKindOf({ type: row.mimetype, name: row.name })
+  if (kind === 'image') {
+    const data = await STORAGE.readFile(row.path)
+    return { type: 'image', data: Buffer.isBuffer(data) ? data : Buffer.from(data), mediaType: row.mimetype, name: row.name }
+  }
+  const content = String(await STORAGE.readFile(row.path, 'utf8'))
+  const truncated = content.length > TEXT_CHARS_FOR_MODEL
+  return { type: 'text', text: truncated ? content.slice(0, TEXT_CHARS_FOR_MODEL) : content, name: row.name, truncated }
+}
+
+/** Removes these files from storage and their rows. */
+export async function removeAttachmentRows(ids: string[]): Promise<void> {
+  if (!ids.length) return
+  const rows = await getRepository(Attachment).find({ where: ids.map(id => ({ id, refType: CHAT_ATTACHMENT_REF })) as any })
+  for (const row of rows) {
+    try {
+      await STORAGE.deleteFile((row as any).path)
+    } catch {
+      /* already gone from storage */
+    }
+  }
+  if (rows.length) await getRepository(Attachment).delete(rows.map(row => (row as any).id))
+}
+
+/** Removes a conversation's files from storage and their rows - the purge's part (§9-5). */
+export async function removeSessionFiles(session: { id?: string; domain?: { id?: string } }): Promise<void> {
+  const rows = await getRepository(Attachment).find({ where: { refType: CHAT_ATTACHMENT_REF, refBy: session.id } as any })
+  for (const row of rows) {
+    try {
+      await STORAGE.deleteFile((row as any).path)
+    } catch {
+      /* A file already gone from storage must not keep its row alive. */
+    }
+  }
+  if (rows.length) await getRepository(Attachment).delete(rows.map(row => (row as any).id))
+}