@things-factory/ai-assistant 10.1.106 → 10.1.108

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-assistant",
-  "version": "10.1.106",
+  "version": "10.1.108",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -35,11 +35,12 @@
     "@operato/styles": "^10.0.0",
     "@things-factory/ai-client-base": "^10.1.81",
     "@things-factory/apptool-base": "^10.1.106",
-    "@things-factory/attachment-base": "^10.1.106",
-    "@things-factory/auth-base": "^10.1.106",
+    "@things-factory/attachment-base": "^10.1.107",
+    "@things-factory/auth-base": "^10.1.107",
     "@things-factory/env": "^10.1.20",
     "@things-factory/shell": "^10.1.106",
     "dompurify": "^3.0.0",
+    "exceljs": "4.2.0",
     "graphql-scalars": "^1.22.0",
     "graphql-tag": "^2.12.6",
     "graphql-upload": "^15.0.2",
@@ -51,5 +52,5 @@
     "copyfiles": "^2.4.1",
     "rimraf": "^5.0.0"
   },
-  "gitHead": "8d78c14708420773ec32d18b8dd44c300771c44d"
+  "gitHead": "b9e1747b2796c323ba8b0eebce7b4628be1e3fd0"
 }

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

@@ -55,7 +55,7 @@ import { inviteMentionedUsers } from './chat-session-participant/mention-invite.
 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 { attachmentHistoryLine, refuseAttachments, textCharsOf } 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'
@@ -444,7 +444,7 @@ export class AssistantChatResolver {
       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)
+          const file = await attachmentForModel(row, textCharsOf(getAssistantMode(input.mode?.kind ?? '')?.attachments))
           if (file.type === 'image') {
             parts.push({ type: 'image', source: { kind: 'base64', data: file.data, mediaType: file.mediaType } })
           } else {

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

@@ -58,7 +58,7 @@ class AssistantModeView {
 
   @Field(() => GraphQLJSON, {
     nullable: true,
-    description: "What this conversation accepts as attachments: { kinds: ('image'|'text')[], maxBytes, maxFiles }. Null: none."
+    description: "What this conversation accepts as attachments: { kinds: ('image'|'text'|'spreadsheet')[], maxBytes, maxFiles, maxChars }. Null: none."
   })
   attachments?: any
 }

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

@@ -6,7 +6,11 @@
  * 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'
+/*
+ * 'spreadsheet' is a kind a mode opens, never a file the door receives: the screen reads each .xlsx sheet into CSV
+ * text before sending (client/utils/spreadsheet-text.ts), so a mode that takes spreadsheets takes that text.
+ */
+export type AttachmentKind = 'image' | 'text' | 'spreadsheet'
 
 export interface AttachmentPolicy {
   kinds: AttachmentKind[]
@@ -14,6 +18,8 @@ export interface AttachmentPolicy {
   maxBytes?: number
   /** Per message. */
   maxFiles?: number
+  /** Per text file, the characters the model reads - a sheet read into text longer than this is refused, not cut. */
+  maxChars?: number
 }
 
 export const DEFAULT_MAX_BYTES = 5 * 1024 * 1024
@@ -41,6 +47,16 @@ export type AttachmentRefusal =
   | { code: 'too-many-attachments'; maxFiles: number }
 
 /** `null` when every file may go; otherwise the first reason, by name - said before sending, never cut silently. */
+/** A kind the policy takes - text also when it takes spreadsheets, which arrive as the text of their sheets. */
+function takes(policy: AttachmentPolicy, kind: AttachmentKind): boolean {
+  return policy.kinds.includes(kind) || (kind === 'text' && policy.kinds.includes('spreadsheet'))
+}
+
+/** The characters of a text file the model reads under this policy. */
+export function textCharsOf(policy: AttachmentPolicy | null | undefined): number {
+  return policy?.maxChars ?? TEXT_CHARS_FOR_MODEL
+}
+
 export function refuseAttachments(
   policy: AttachmentPolicy | null | undefined,
   files: { name?: string; type?: string; size?: number }[]
@@ -54,7 +70,7 @@ export function refuseAttachments(
   const maxBytes = policy.maxBytes ?? DEFAULT_MAX_BYTES
   for (const file of files) {
     const kind = attachmentKindOf(file)
-    if (!kind || !policy.kinds.includes(kind)) {
+    if (!kind || !takes(policy, 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 }

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

@@ -16,6 +16,8 @@ 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'
+import { textCharsOf } from './attachment-policy.js'
+import { getAssistantMode } from '../assistant-mode/registry.js'
 
 export const CHAT_ATTACHMENT_CATEGORY = 'chat-attachments'
 
@@ -46,7 +48,7 @@ const readChatAttachment: ToolSpec = {
       return { absent: 'not-found', attachmentId: id, message: 'there is no such attachment in a conversation here.' }
     }
 
-    const file = await attachmentForModel(row)
+    const file = await attachmentForModel(row, textCharsOf(getAssistantMode(session.kind || '')?.attachments))
     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.' } : {}) }

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

@@ -44,10 +44,11 @@ export async function findChatAttachment(domainId: string, sessionId: string, at
 }
 
 /**
- * What the model gets for a file: an image as bytes, a text file as its text (cut at TEXT_CHARS_FOR_MODEL,
+ * What the model gets for a file: an image as bytes, a text file as its text (cut at the mode's maxChars -
+ * TEXT_CHARS_FOR_MODEL when it declares none -
  * and the cut is said), anything else as a line that names it.
  */
-export async function attachmentForModel(row: any): Promise<
+export async function attachmentForModel(row: any, maxChars: number = TEXT_CHARS_FOR_MODEL): Promise<
   | { type: 'image'; data: Buffer; mediaType: string; name: string }
   | { type: 'text'; text: string; name: string; truncated: boolean }
 > {
@@ -57,8 +58,8 @@ export async function attachmentForModel(row: any): Promise<
     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 }
+  const truncated = content.length > maxChars
+  return { type: 'text', text: truncated ? content.slice(0, maxChars) : content, name: row.name, truncated }
 }
 
 /** Removes these files from storage and their rows. */

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

@@ -175,6 +175,16 @@ describe('entering what the person pressed', () => {
     expect(await applyEntryProposal('k2', deps(messages))).toMatchObject({ verdict: 'accepted', applied: 1 })
   })
 
+  it('★ reviewed in the workspace, a proposal is entered only as it was shown there (workspace.md §6-1)', async () => {
+    const { entryProposalHash } = await import('./entry-hash.js')
+    const shownThen = proposal('k1', [row({ spentOn: '2026-09-12', amount: 1 })])
+    const reviewed = entryProposalHash(shownThen)
+    const nowStored = [{ id: 'm1', proposals: [proposal('k1', [row({ spentOn: '2026-09-12', amount: 100 })])] }]
+    expect(await applyEntryProposal('k1', deps(nowStored, { reviewedHash: reviewed }))).toMatchObject({ verdict: 'refused', errorCode: 'review-stale', applied: 0 })
+    expect(written).toEqual([])
+    expect(await applyEntryProposal('k1', deps([{ id: 'm1', proposals: [shownThen] }], { reviewedHash: reviewed }))).toMatchObject({ verdict: 'accepted', applied: 1 })
+  })
+
   it('★ the door is asked again at the moment of writing', async () => {
     const messages = [{ id: 'm1', proposals: [proposal('k1', [row({ spentOn: '2026-09-12', amount: 1 })])] }]
     expect(await applyEntryProposal('k1', deps(messages, { passesDoor: async () => false }))).toMatchObject({ verdict: 'refused', errorCode: 'door-closed' })

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

@@ -13,6 +13,7 @@
 import { PROPOSAL_OUTCOME_PREFIX, PROPOSAL_VERDICTS } from '../chat-message/proposal-outcome.js'
 import { readRecords, stillAsProposed, withChangeChecks, type ChangeRow } from './entry-update.js'
 import { changeToolName, zonedDateTimes, entryGroups, resolveReferences, entryDoorOf, entryTargetOf, entryToolName, rootFieldOf, isBlocked, recordEntryEvent, normalizeEntryRows, withCheckedIssues, type EntryRow, type EntryTarget } from './entry-target.js'
+import { entryProposalHash } from './entry-hash.js'
 
 export interface StoredProposalMessage {
   id: string
@@ -49,6 +50,8 @@ export interface EntryApplyDeps {
   execute(document: string, variables: Record<string, unknown>): Promise<{ data?: any; errors?: readonly { message: string }[] }>
   state: any
   report?(message: string, error: unknown): void
+  /** The fingerprint of what the AI 작업판 showed, when the person reviewed it there - entered only if the proposal is still that one. */
+  reviewedHash?: string
 }
 
 const nothing = (verdict: EntryApplyOutcome['verdict'], errorCode: string): EntryApplyOutcome => ({ verdict, errorCode, applied: 0, missed: 0, rows: [] })
@@ -73,6 +76,8 @@ export async function applyEntryProposal(key: string, deps: EntryApplyDeps, targ
   if (proposal.kind !== 'entry') return nothing('refused', 'not-an-entry-proposal')
   if (superseded) return nothing('refused', 'superseded')
   if (deps.answered) return nothing('refused', 'already-answered')
+  /* What the 작업판 showed and what is entered are one proposal (design/ai/workspace.md §6-1). */
+  if (deps.reviewedHash && deps.reviewedHash !== entryProposalHash(proposal)) return nothing('refused', 'review-stale')
 
   const target = targetOf(proposal.target)
   if (!target) return nothing('unavailable', 'unknown-entry-target')

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

@@ -0,0 +1,35 @@
+/*
+ * One 입력안's fingerprint - what the AI 작업판 showed and what the card enters are the same proposal
+ * (operato-application/design/ai/workspace.md §6-1). The screen's copy and the server's are one rule;
+ * `test/entry-hash-agree.test.ts` runs both over one table.
+ *
+ * It covers what is entered: the key, the target, create or change, and each row's index, record and values.
+ */
+
+const canonical = (value: unknown): string => {
+  if (value === null || value === undefined) return 'null'
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  if (typeof value === 'object')
+    return `{${Object.keys(value as object)
+      .filter(name => (value as any)[name] !== undefined)
+      .sort()
+      .map(name => `${JSON.stringify(name)}:${canonical((value as any)[name])}`)
+      .join(',')}}`
+  return JSON.stringify(value)
+}
+
+/** FNV-1a over the canonical text - a fingerprint to compare, not a secret. */
+export function entryProposalHash(proposal: any): string {
+  const text = canonical({
+    key: proposal?.key,
+    target: proposal?.target,
+    op: proposal?.op ?? 'create',
+    rows: (proposal?.rows ?? []).map((row: any) => ({ index: row?.index, id: row?.id, values: row?.values ?? {} }))
+  })
+  let hash = 0x811c9dc5
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193) >>> 0
+  }
+  return `${hash.toString(16).padStart(8, '0')}-${text.length.toString(16)}`
+}

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

@@ -28,7 +28,8 @@ export class EntryProposalResolver {
   async applyEntryProposal(
     @Arg('sessionId') sessionId: string,
     @Arg('proposalKey') proposalKey: string,
-    @Ctx() context: ResolverContext
+    @Ctx() context: ResolverContext,
+    @Arg('reviewedHash', { nullable: true, description: 'The fingerprint of the proposal as the AI workspace showed it; a proposal that is no longer that one is refused.' }) reviewedHash?: string
   ): Promise<EntryApplyOutcome> {
     const { domain, user } = context.state
     const session = await getRepository(ChatSession).findOneBy({ id: sessionId, domain: { id: domain.id } } as any)
@@ -63,7 +64,8 @@ export class EntryProposalResolver {
        * door opens its own transaction per row (entry-tools.ts `runAsCaller`).
        */
       execute: runAsCaller(context),
-      report: (message, error) => logger.error(message, error)
+      report: (message, error) => logger.error(message, error),
+      reviewedHash: reviewedHash || undefined
     })
   }
 }

package/test/entry-workspace.test.ts

@@ -0,0 +1,89 @@
+/*
+ * Reviewing a 입력안 in the AI 작업판 (operato-application/design/ai/workspace.md §6-1): read-only on the page,
+ * entered from the dock's card - and only as the page showed it.
+ */
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+import * as screen from '../client/utils/entry-hash'
+import * as server from '../server/service/data-entry/entry-hash'
+import { entryForReview, entryReviewAddress, offersWorkspaceReview, rememberReviewed, reviewedHashOf, reviewStillHolds } from '../client/utils/entry-workspace'
+import { entryProposalHandler } from '../client/utils/entry-proposal'
+
+const proposal = (key: string, values: any[], more: any = {}) => ({ key, kind: 'entry', target: 'office.contract', rows: values.map((v, index) => ({ index, values: v, sources: [], issues: [] })), columns: [], ...more })
+
+describe('the fingerprint', () => {
+  const table = [
+    proposal('k1', [{ name: 'A', amount: 1 }]),
+    proposal('k1', [{ amount: 1, name: 'A' }]),
+    proposal('k1', [{ name: 'A', amount: 2 }]),
+    proposal('k2', [{ name: 'A', amount: 1 }]),
+    { ...proposal('k1', [{ name: 'A' }]), op: 'update' },
+    proposal('k1', [{ name: 'A', ref: { id: 'x', label: '엑스' } }]),
+    {}
+  ]
+  it('is one rule on the screen and at the door', () => {
+    for (const one of table) expect(screen.entryProposalHash(one)).toBe(server.entryProposalHash(one))
+  })
+  it('ignores the order of fields, and moves with anything entered', () => {
+    expect(screen.entryProposalHash(table[0])).toBe(screen.entryProposalHash(table[1]))
+    const distinct = new Set([table[0], table[2], table[3], table[4], table[5]].map(screen.entryProposalHash))
+    expect(distinct.size).toBe(5)
+  })
+})
+
+describe('reviewing in the workspace', () => {
+  it('is offered when the card is long or wide', () => {
+    expect(offersWorkspaceReview(proposal('k', Array.from({ length: 21 }, () => ({}))))).toBe(true)
+    expect(offersWorkspaceReview(proposal('k', [{}], { columns: Array.from({ length: 7 }, (_, i) => ({ name: `c${i}` })) }))).toBe(true)
+    expect(offersWorkspaceReview(proposal('k', [{}], { columns: [{ name: 'a' }] }))).toBe(false)
+    expect(entryReviewAddress('s 1', 'k/1')).toBe('assistant-workspace?session=s+1&entry=k%2F1')
+  })
+
+  it('finds the card by its key and says when a newer card of the same record replaced it', () => {
+    const messages = [
+      { id: 'm1', createdAt: 't1', proposalsJson: [proposal('k1', [{}])] },
+      { id: 'm2', proposalsJson: [{ ...proposal('u1', [{}]), op: 'update' }] },
+      { id: 'm3', proposalsJson: [proposal('k2', [{}])] }
+    ]
+    expect(entryForReview(messages, 'k1')).toMatchObject({ createdAt: 't1', superseded: true })
+    expect(entryForReview(messages, 'u1').superseded).toBe(false)
+    expect(entryForReview(messages, 'k2').superseded).toBe(false)
+    expect(entryForReview(messages, 'none')).toEqual({ superseded: false })
+  })
+
+  it('remembers what was shown; the card holds only while the proposal is that one', () => {
+    const store = new Map<string, string>()
+    const storage = { setItem: (k: string, v: string) => void store.set(k, v), getItem: (k: string) => store.get(k) ?? null }
+    const shown = proposal('k1', [{ amount: 1 }])
+    rememberReviewed(shown, storage)
+    const reviewed = reviewedHashOf('k1', storage)
+    expect(reviewStillHolds(shown, reviewed)).toBe(true)
+    expect(reviewStillHolds(proposal('k1', [{ amount: 9 }]), reviewed)).toBe(false)
+    expect(reviewStillHolds(shown, undefined)).toBe(true)
+    const blocked = { setItem: () => { throw new Error('blocked') }, getItem: () => { throw new Error('blocked') } }
+    expect(() => rememberReviewed(shown, blocked as any)).not.toThrow()
+    expect(reviewedHashOf('k1', blocked as any)).toBeUndefined()
+  })
+
+  it('★ the card refuses a proposal that changed after review, before asking the server - and sends the fingerprint when it holds', async () => {
+    const asked: any[] = []
+    const t = (key: string, options?: any) => options?.defaultValue ?? key
+    const shown = proposal('k1', [{ amount: 1 }])
+    const reviewed = screen.entryProposalHash(shown)
+    const handler = entryProposalHandler(async (...args) => (asked.push(args), { verdict: 'accepted', applied: 1, missed: 0, rows: [] }), t, () => reviewed)
+    const stale = await handler(proposal('k1', [{ amount: 2 }]), { sessionId: 's1' } as any)
+    expect(stale).toMatchObject({ verdict: 'refused', errorCode: 'review-stale' })
+    expect(asked).toEqual([])
+    expect(await handler(shown, { sessionId: 's1' } as any)).toMatchObject({ verdict: 'accepted' })
+    expect(asked).toEqual([['s1', 'k1', reviewed]])
+  })
+
+  it('the page is read-only - it draws the review wide and enters nothing; the dock card opens it', () => {
+    const page = readFileSync(join(__dirname, '..', 'client', 'pages', 'assistant-workspace-page.ts'), 'utf8')
+    expect(page).toContain('<ox-assistant-entry-review wide .proposal=${p}>')
+    expect(page).not.toMatch(/applyEntryProposal|runProposal|executeProposal/)
+    const chat = readFileSync(join(__dirname, '..', 'client', 'components', 'assistant-chat.ts'), 'utf8')
+    expect(chat).toContain('entryReviewAddress(this.sessionId!, key)')
+  })
+})

package/test/pasted-table.test.ts

@@ -0,0 +1,140 @@
+/*
+ * A table pasted into the composer (client/utils/pasted-table.ts) - what is a table, what is words, and the file it
+ * becomes. The clipboards are the shapes Excel, Google Sheets and a browser put there.
+ */
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+import { pastedTable, pastedTableFile, pastedTableText, tableOfHtml, tableOfText } from '../client/utils/pasted-table'
+
+/* Excel for the web / desktop: a whole document, a style block, a conditional comment, classes,   in an empty cell. */
+const EXCEL_HTML = `<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:x="urn:schemas-microsoft-com:office:excel">
+<head><meta charset="utf-8"><style>
+.xl65 { mso-number-format:"\\#\\,\\#\\#0"; }
+td { padding: 0 }
+</style></head>
+<body link="#0563C1">
+<!--StartFragment-->
+<table border=0 cellpadding=0 cellspacing=0 width=300>
+ <col width=100 span=3>
+ <tr height=20>
+  <td height=20 width=100>이용일</td>
+  <td width=100>가맹점</td>
+  <td width=100>이용금액</td>
+ </tr>
+ <tr height=20>
+  <td height=20 class=xl66 align=right>2026-09-12</td>
+  <td>카카오T</td>
+  <td class=xl65 align=right>12,400</td>
+ </tr>
+ <tr height=20>
+  <td height=20 class=xl66 align=right>2026-09-13</td>
+  <td>스타벅스 &amp; 브런치</td>
+  <td class=xl65 align=right>5,000</td>
+ </tr>
+ <tr height=20>
+  <td height=20>&nbsp;</td>
+  <td>합계</td>
+  <td class=xl65 align=right>17,400</td>
+ </tr>
+</table>
+<!--EndFragment-->
+</body></html>`
+
+const EXCEL_TEXT = '이용일\t가맹점\t이용금액\r\n2026-09-12\t카카오T\t12,400\r\n2026-09-13\t스타벅스 & 브런치\t5,000\r\n\t합계\t17,400\r\n'
+
+/* Google Sheets: its own wrapper and a colgroup, cells without closing tags never happen here but a <br> in a cell does. */
+const SHEETS_HTML =
+  '<google-sheets-html-origin><style type="text/css"><!--td {border: 1px solid #cccccc;}--></style>' +
+  '<table xmlns="http://www.w3.org/1999/xhtml" cellspacing="0" cellpadding="0" dir="ltr" border="1"><colgroup><col width="100"/><col width="100"/></colgroup>' +
+  '<tbody><tr style="height:21px;"><td style="overflow:hidden;">품목</td><td>비고</td></tr>' +
+  '<tr style="height:21px;"><td>볼트 M8</td><td>1차 납품<br/>나머지 다음 주</td></tr></tbody></table></google-sheets-html-origin>'
+
+describe('a pasted table', () => {
+  it('★ Excel - the HTML is read: the header, the rows, an empty cell kept in its column, &amp; decoded', () => {
+    const table = pastedTable({ html: EXCEL_HTML, text: EXCEL_TEXT })
+    expect(table).toEqual({
+      columns: 3,
+      rows: [
+        ['이용일', '가맹점', '이용금액'],
+        ['2026-09-12', '카카오T', '12,400'],
+        ['2026-09-13', '스타벅스 & 브런치', '5,000'],
+        ['', '합계', '17,400']
+      ]
+    })
+  })
+
+  it('★ the plain text alone gives the same table - a spreadsheet\'s tab-separated lines', () => {
+    expect(pastedTable({ text: EXCEL_TEXT })?.rows).toEqual(pastedTable({ html: EXCEL_HTML })?.rows)
+  })
+
+  it('Google Sheets - its wrapper and style are not cells, a line break in a cell stays in the cell', () => {
+    expect(tableOfHtml(SHEETS_HTML)).toEqual([
+      ['품목', '비고'],
+      ['볼트 M8', '1차 납품 나머지 다음 주']
+    ])
+  })
+
+  it('a cell spanning columns keeps the next cells in their columns', () => {
+    expect(tableOfHtml('<table><tr><td colspan="2">9월</td><td>합계</td></tr><tr><td>a</td><td>b</td><td>3</td></tr></table>')).toEqual([
+      ['9월', '', '합계'],
+      ['a', 'b', '3']
+    ])
+  })
+
+  it('a quoted cell of the plain text holds its line break and its tab', () => {
+    expect(tableOfText('품목\t비고\n볼트\t"1차\n2차\t분할"\n너트\t-\n')).toEqual([
+      ['품목', '비고'],
+      ['볼트', '1차 2차 분할'],
+      ['너트', '-']
+    ])
+  })
+
+  it('★ a web page whose words lie mostly outside its table is words, not a table paste', () => {
+    const page = '<p>9월 경비 정산 안내입니다. 아래 표를 참고하시고 이번 주 금요일까지 제출해 주십시오.</p><table><tr><td>a</td><td>b</td></tr><tr><td>c</td><td>d</td></tr></table>'
+    expect(tableOfHtml(page)).toBeNull()
+    expect(pastedTable({ html: page, text: '9월 경비 정산 안내입니다.\n\na\tb\nc\td' })).toBeNull()
+  })
+
+  it('★ words are words - a sentence, a sentence with one tab, one row, one column', () => {
+    expect(pastedTable({ text: '카카오T 12,400원 경비로 올려 줘' })).toBeNull()
+    expect(pastedTable({ text: '메모:\t내일 다시\n오늘은 여기까지\n그리고 하나 더' })).toBeNull()
+    expect(pastedTable({ text: 'a\tb\tc\n' })).toBeNull()
+    expect(pastedTable({ html: '<table><tr><td>a</td></tr><tr><td>b</td></tr></table>' })).toBeNull()
+  })
+
+  it('★ the file has the shape of a read sheet - a line naming it, each row led by its number, CSV quoting', () => {
+    const table = pastedTable({ text: EXCEL_TEXT })!
+    expect(pastedTableText(table, '붙여넣은 표').split('\n')).toEqual([
+      '# 붙여넣은 표 · a table the person pasted · the first column is the row number in the pasted table',
+      '1,이용일,가맹점,이용금액',
+      '2,2026-09-12,카카오T,"12,400"',
+      '3,2026-09-13,스타벅스 & 브런치,"5,000"',
+      '4,,합계,"17,400"',
+      ''
+    ])
+  })
+
+  const nameOf = (rows: number) => `붙여넣은 표 ${rows}행`
+
+  it('★ a conversation that takes text gets a CSV file - one that takes none keeps the paste as words', () => {
+    expect(pastedTableFile({ text: EXCEL_TEXT }, { kinds: ['image', 'text'] }, nameOf)).toEqual({ name: '붙여넣은 표 4행.csv', text: pastedTableText(pastedTable({ text: EXCEL_TEXT })!, '붙여넣은 표 4행') })
+    expect(pastedTableFile({ text: EXCEL_TEXT }, { kinds: ['spreadsheet'] }, nameOf)).toMatchObject({ name: '붙여넣은 표 4행.csv' })
+    expect(pastedTableFile({ text: EXCEL_TEXT }, { kinds: ['image'] }, nameOf)).toBeNull()
+    expect(pastedTableFile({ text: EXCEL_TEXT }, null, nameOf)).toBeNull()
+    expect(pastedTableFile({ text: '그냥 글입니다' }, { kinds: ['text'] }, nameOf)).toBeNull()
+  })
+
+  it('★ a table longer than the model reads is refused, never cut', () => {
+    expect(pastedTableFile({ text: EXCEL_TEXT }, { kinds: ['text'], maxChars: 50 }, nameOf)).toEqual({ refusal: { code: 'attachment-paste-too-long', rows: 4, maxChars: 50 } })
+  })
+
+  it('★ the composer takes the table before the files - the picture a spreadsheet puts beside it is not attached', () => {
+    const source = readFileSync(join(__dirname, '../client/components/assistant-chat.ts'), 'utf8')
+    const paste = source.slice(source.indexOf('private onComposerPaste('), source.indexOf('private onComposerDragOver('))
+    expect(paste.indexOf('pastedTableFile(')).toBeGreaterThan(0)
+    expect(paste.indexOf('pastedTableFile(')).toBeLessThan(paste.indexOf("item.kind === 'file'"))
+    expect(paste).toMatch(/e\.preventDefault\(\)[\s\S]*?return\n/)
+  })
+})
+

package/test/spreadsheet-text.test.ts

@@ -0,0 +1,92 @@
+/*
+ * A spreadsheet read into the text a conversation carries (design/ai/shared-dock.md §9-5): computed values, ISO
+ * dates, the sheet's own row numbers kept, .xls refused by name, and a sheet longer than the limit refused - never cut.
+ */
+import ExcelJS from 'exceljs'
+
+import * as server from '../server/service/chat-session/attachment-policy'
+import * as screen from '../client/utils/attachment-policy'
+import { cellText, readSpreadsheet, sheetFileName, sheetText, spreadsheetKindOf } from '../client/utils/spreadsheet-text'
+
+async function workbook(build: (wb: any) => void): Promise<Uint8Array> {
+  const wb = new ExcelJS.Workbook()
+  build(wb)
+  return new Uint8Array(await wb.xlsx.writeBuffer())
+}
+
+describe('a spreadsheet as text', () => {
+  it('keeps the sheet\'s own row numbers - an empty row is left out, never renumbered', async () => {
+    const data = await workbook(wb => {
+      const ws = wb.addWorksheet('9월')
+      ws.getCell('A1').value = '거래일'
+      ws.getCell('B1').value = '금액'
+      ws.getCell('A2').value = new Date(Date.UTC(2026, 8, 22))
+      ws.getCell('B2').value = 4400000
+      /* row 3 empty */
+      ws.getCell('A4').value = new Date(Date.UTC(2026, 8, 23, 9, 30))
+      ws.getCell('B4').value = { formula: 'B2/8', result: 550000 }
+      ws.getCell('C4').value = '메모, "따옴표"'
+    })
+    const read: any = await readSpreadsheet(data, '거래내역.xlsx', 20_000, ExcelJS.Workbook)
+    expect(read.files.map((one: any) => one.name)).toEqual(['거래내역 - 9월.csv'])
+    expect(read.files[0].text.split('\n').slice(1, 4)).toEqual(['1,거래일,금액', '2,2026-09-22,4400000', '4,2026-09-23T09:30:00,550000,"메모, ""따옴표"""'])
+  })
+
+  it('reads every sheet with something in it, and says so when none has', async () => {
+    const two = await workbook(wb => {
+      wb.addWorksheet('빈 시트')
+      wb.addWorksheet('계약').getCell('A1').value = 'H2026001'
+    })
+    expect(((await readSpreadsheet(two, 'a.xlsx', 20_000, ExcelJS.Workbook)) as any).files.map((one: any) => one.name)).toEqual(['a - 계약.csv'])
+    const none = await workbook(wb => wb.addWorksheet('빈 시트'))
+    expect(await readSpreadsheet(none, 'b.xlsx', 20_000, ExcelJS.Workbook)).toEqual({ refusal: { code: 'attachment-sheet-empty', name: 'b.xlsx' } })
+  })
+
+  it('refuses a sheet longer than the limit as text - a small file can be a long text - and never cuts it', async () => {
+    const data = await workbook(wb => {
+      const ws = wb.addWorksheet('원장')
+      for (let i = 1; i <= 400; i++) ws.addRow([i, '가나다라마바사아자차카타파하', 1234567])
+    })
+    expect(data.byteLength).toBeLessThan(20_000)
+    expect(await readSpreadsheet(data, 'big.xlsx', 5_000, ExcelJS.Workbook)).toEqual({ refusal: { code: 'attachment-sheet-too-long', name: 'big.xlsx · 원장', maxChars: 5_000 } })
+    const fits: any = await readSpreadsheet(data, 'big.xlsx', 50_000, ExcelJS.Workbook)
+    expect(fits.files[0].text.trim().split('\n')).toHaveLength(401)
+  })
+
+  it('names a file that is not a workbook instead of failing silently', async () => {
+    expect(await readSpreadsheet(new TextEncoder().encode('not a zip'), 'x.xlsx', 20_000, ExcelJS.Workbook)).toEqual({ refusal: { code: 'attachment-sheet-unreadable', name: 'x.xlsx' } })
+  })
+
+  it('tells .xlsx from the old .xls, by type or by name', () => {
+    expect(spreadsheetKindOf({ name: '원장.XLSX' })).toBe('xlsx')
+    expect(spreadsheetKindOf({ name: 'x', type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' })).toBe('xlsx')
+    expect(spreadsheetKindOf({ name: '옛 원장.xls' })).toBe('xls')
+    expect(spreadsheetKindOf({ name: 'a.csv', type: 'text/csv' })).toBeNull()
+  })
+
+  it('reads a cell as Excel shows its value', () => {
+    expect(cellText({ richText: [{ text: '굵은' }, { text: ' 글' }] })).toBe('굵은 글')
+    expect(cellText({ text: '링크', hyperlink: 'https://x' })).toBe('링크')
+    expect(cellText({ formula: 'A1+1' })).toBe('')
+    expect(cellText({ error: '#DIV/0!' })).toBe('#DIV/0!')
+    expect(cellText(true)).toBe('true')
+    expect(sheetText('f.xlsx', 's', [{ number: 7, cells: ['a', '', ''] }])).toBe('# f.xlsx · sheet "s" · the first column is the sheet\'s own row number\n7,a\n')
+    expect(sheetFileName('a/b.xlsx', '9/10월')).toBe('a/b - 9_10월.csv')
+  })
+})
+
+describe('a mode that takes spreadsheets takes their text - on the screen and at the door alike', () => {
+  const policy = { kinds: ['spreadsheet'] } as any
+  const sheet = [{ name: '거래내역 - 9월.csv', type: 'text/csv', size: 10 }]
+  it('the sheets\' text passes; an image does not', () => {
+    for (const rule of [screen, server]) {
+      expect(rule.refuseAttachments(policy, sheet)).toBeNull()
+      expect(rule.refuseAttachments(policy, [{ name: 'a.png', type: 'image/png', size: 1 }])).toEqual({ code: 'attachment-kind-not-accepted', name: 'a.png', kinds: ['spreadsheet'] })
+    }
+  })
+  it('the limit of text the model reads is the mode\'s, the same on both sides', () => {
+    expect(screen.textCharsOf({ kinds: ['spreadsheet'], maxChars: 150_000 })).toBe(150_000)
+    expect(screen.textCharsOf(undefined)).toBe(server.TEXT_CHARS_FOR_MODEL)
+    expect(screen.TEXT_CHARS_FOR_MODEL).toBe(server.TEXT_CHARS_FOR_MODEL)
+  })
+})

package/translations/en.json

@@ -278,5 +278,16 @@
   "ai-assistant.entry.issue.not-a-reference": "not a record it can point to",
   "ai-assistant.entry.groups": "{count} records",
   "ai-assistant.entry.groups-kept-out": "{count} records kept out whole",
-  "ai-assistant.entry.issue.check-failed": "could not be checked - not changed"
+  "ai-assistant.entry.issue.check-failed": "could not be checked - not changed",
+  "ai-assistant.text.attachment-xls-not-read": "{name} is an old Excel file (.xls) and is not read. Save it as .xlsx in Excel and attach it again.",
+  "ai-assistant.text.attachment-sheet-too-long": "The sheet {name} is longer than {maxChars} characters as text and was not sent. Split it and attach the parts.",
+  "ai-assistant.text.attachment-paste-too-long": "The pasted table is longer than {maxChars} characters as text and was not sent. Paste it in parts.",
+  "ai-assistant.text.pasted-table-name": "pasted table ({rows} rows)",
+  "ai-assistant.text.attachment-sheet-unreadable": "{name} cannot be read as an Excel file.",
+  "ai-assistant.text.attachment-sheet-empty": "{name} has no sheet with anything in it.",
+  "ai-assistant.entry.review-in-workspace": "review in the workspace",
+  "ai-assistant.entry.review-stale": "this proposal changed after it was reviewed in the workspace - review it again before entering.",
+  "ai-assistant.workspace.entry-not-found": "there is no proposal here that you can see.",
+  "ai-assistant.workspace.entry-superseded": "a newer card replaced this one in the conversation - review that one.",
+  "ai-assistant.workspace.entry-press-in-dock": "this is a review. Enter the rows with the button on the card in the AI dock."
 }

package/translations/ja.json

@@ -278,5 +278,16 @@
   "ai-assistant.entry.issue.not-a-reference": "参照先の記録が分かりません",
   "ai-assistant.entry.groups": "{count}件",
   "ai-assistant.entry.groups-kept-out": "{count}件は行が止まり全体を入力しません",
-  "ai-assistant.entry.issue.check-failed": "検査できなかったため修正しません"
+  "ai-assistant.entry.issue.check-failed": "検査できなかったため修正しません",
+  "ai-assistant.text.attachment-xls-not-read": "{name} は古い Excel 形式 (.xls) のため読み込みません。Excel で .xlsx として保存し、もう一度添付してください。",
+  "ai-assistant.text.attachment-sheet-too-long": "シート {name} はテキストにすると {maxChars} 文字を超えるため送信しませんでした。分けて添付してください。",
+  "ai-assistant.text.attachment-paste-too-long": "貼り付けた表はテキストにすると {maxChars} 文字を超えるため送信しませんでした。分けて貼り付けてください。",
+  "ai-assistant.text.pasted-table-name": "貼り付けた表 {rows}行",
+  "ai-assistant.text.attachment-sheet-unreadable": "{name} を Excel ファイルとして読み込めません。",
+  "ai-assistant.text.attachment-sheet-empty": "{name} には内容のあるシートがありません。",
+  "ai-assistant.entry.review-in-workspace": "作業ボードで確認",
+  "ai-assistant.entry.review-stale": "作業ボードで確認した後に入力案が変わりました。もう一度確認してから入力してください。",
+  "ai-assistant.workspace.entry-not-found": "表示できる入力案はありません。",
+  "ai-assistant.workspace.entry-superseded": "会話の中で新しいカードがこのカードに置き換わりました。そちらを確認してください。",
+  "ai-assistant.workspace.entry-press-in-dock": "これは確認画面です。入力は AI ドックのカードのボタンで行います。"
 }

package/translations/ko.json

@@ -278,5 +278,16 @@
   "ai-assistant.entry.issue.not-a-reference": "가리키는 기록을 알 수 없습니다",
   "ai-assistant.entry.groups": "{count}건",
   "ai-assistant.entry.groups-kept-out": "{count}건은 줄이 막혀 통째로 입력하지 않습니다",
-  "ai-assistant.entry.issue.check-failed": "검사를 하지 못해 고치지 않습니다"
+  "ai-assistant.entry.issue.check-failed": "검사를 하지 못해 고치지 않습니다",
+  "ai-assistant.text.attachment-xls-not-read": "{name} 은 옛 엑셀 형식(.xls)이라 읽지 않습니다. 엑셀에서 .xlsx 로 저장해 다시 첨부해 주십시오.",
+  "ai-assistant.text.attachment-sheet-too-long": "{name} 시트는 글자로 바꾸면 {maxChars} 자를 넘어 보내지 않았습니다. 시트를 나눠 첨부해 주십시오.",
+  "ai-assistant.text.attachment-paste-too-long": "붙여넣은 표가 글자로 {maxChars} 자를 넘어 보내지 않았습니다. 나눠서 붙여넣어 주십시오.",
+  "ai-assistant.text.pasted-table-name": "붙여넣은 표 {rows}행",
+  "ai-assistant.text.attachment-sheet-unreadable": "{name} 을 엑셀 파일로 읽을 수 없습니다.",
+  "ai-assistant.text.attachment-sheet-empty": "{name} 에 내용이 있는 시트가 없습니다.",
+  "ai-assistant.entry.review-in-workspace": "작업판에서 검토",
+  "ai-assistant.entry.review-stale": "작업판에서 검토한 뒤 입력안이 바뀌었습니다. 다시 검토한 뒤 입력하십시오.",
+  "ai-assistant.workspace.entry-not-found": "볼 수 있는 입력안이 없습니다.",
+  "ai-assistant.workspace.entry-superseded": "대화에서 더 새로운 카드가 이 카드를 대신했습니다. 그 카드를 검토하십시오.",
+  "ai-assistant.workspace.entry-press-in-dock": "검토 화면입니다. 입력은 AI 도크의 카드에 있는 단추로 합니다."
 }