@things-factory/ai-assistant 10.1.90 → 10.1.97

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

@@ -9,7 +9,11 @@
  */
 import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
 
+import { findRecords, proposeChanges, changeableFields, type GraphqlRunner } from './entry-update.js'
 import {
+  changeToolName,
+  findToolName,
+  rootFieldOf,
   declareEntryTarget,
   entryTotals,
   verifyRowsAgainstSources,
@@ -99,7 +103,71 @@ export async function proposeEntries(target: EntryTarget, args: any, context: an
   }
 }
 
-export function entryCategoryOf(target: EntryTarget): ToolCategory {
+/**
+ * The application's API as the person who asked - the tool's own request state, no transaction handed on.
+ * Loaded late so the rules are tested without the shell.
+ */
+export const runAsCaller = (context: any): GraphqlRunner => async (document, variables) => {
+  const [{ GraphqlLocalClient }, { default: gql }] = await Promise.all([import('@things-factory/shell'), import('graphql-tag')])
+  const { tx: _tx, afterCommit: _after, ...state } = context?.state ?? {}
+  const operation = /^\s*mutation\b/.test(document) ? 'mutate' : 'query'
+  const result: any =
+    operation === 'mutate'
+      ? await GraphqlLocalClient.client.mutate({ mutation: gql(document), variables, context: { state, t: context?.t } })
+      : await GraphqlLocalClient.client.query({ query: gql(document), variables, context: { state, t: context?.t }, fetchPolicy: 'no-cache' })
+  return { data: result.data, errors: result.errors }
+}
+
+/** The two tools of changing records - finding candidates, and the 수정안 (design/ai/data-entry.md §5-1). */
+function changeSpecs(target: EntryTarget, run: (context: any) => GraphqlRunner): ToolSpec[] {
+  const update = target.update
+  if (!update) return []
+  const readDoor = rootFieldOf(update.read.query, 'query')
+  const specs: ToolSpec[] = [
+    {
+      kind: 'read',
+      name: changeToolName(target.key),
+      /* The person must be able to read the records and change them by hand. */
+      doors: [rootFieldOf(update.mutation, 'mutation'), readDoor],
+      description:
+        `Propose changes to existing records: ${target.description} ` +
+        'Name each record by ref: "current" (the one on screen), "selected" (every row selected on screen) or an id a find tool returned. ' +
+        'The server reads each record, and the card shows what it holds now and what it becomes; nothing changes until the person presses it.',
+      schema: {
+        type: 'object',
+        properties: {
+          changes: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                ref: { type: 'string', description: '"current", "selected", or a record id from a find tool - never a guessed id.' },
+                values: { type: 'object', description: 'Only the fields that change, with their new values.', properties: Object.fromEntries(changeableFields(target).map(field => [field.name, fieldSchema(field)])) }
+              },
+              required: ['ref', 'values']
+            }
+          },
+          note: { type: 'string', description: 'One line for the card.' }
+        },
+        required: ['changes']
+      },
+      builder: (args: any, context: any) => proposeChanges(target, args, context, run(context))
+    } as ToolSpec
+  ]
+  if (update.find) {
+    specs.push({
+      kind: 'read',
+      name: findToolName(target.key),
+      doors: [rootFieldOf(update.find.query, 'query')],
+      description: `Find existing records to change from what the person described: ${target.description} Returns candidates with their ids.`,
+      schema: { type: 'object', properties: Object.fromEntries(update.find.criteria.map(field => [field.name, fieldSchema(field)])) },
+      builder: (args: any, context: any) => findRecords(target, args, run(context))
+    } as ToolSpec)
+  }
+  return specs
+}
+
+export function entryCategoryOf(target: EntryTarget, run: (context: any) => GraphqlRunner = runAsCaller): ToolCategory {
   const name = entryToolName(target.key)
   const spec = {
     kind: 'read',
@@ -157,9 +225,15 @@ export function entryCategoryOf(target: EntryTarget): ToolCategory {
       '- Give each row its sources: which attachment and where in it. A value the person gave or corrected in the conversation adds the source where: "the person\'s message". The server looks for each row\'s numbers and dates in the cited file and marks what it does not find.',
       '- When the material prints a total, pass it as declaredTotal exactly as printed - do not add it up yourself.',
       `- ${name} only proposes. Nothing is entered until the person presses the button on the card - never say the records were entered.`,
-      `- When the person corrects or drops rows, call ${name} again with the whole corrected set. The newest card replaces the earlier ones; an earlier card can no longer be entered.`
+      `- When the person corrects or drops rows, call ${name} again with the whole corrected set. The newest card replaces the earlier ones; an earlier card can no longer be entered.`,
+      ...(target.update
+        ? [
+            `- To change records that exist, call ${changeToolName(target.key)}. Use ref "current" for the record on screen and "selected" for the rows selected there.${target.update.find ? ` Otherwise call ${findToolName(target.key)} first with what the person said; if more than one record matches, list them and ask which - never pick one yourself.` : ' Otherwise ask the person to open or select the record.'}`,
+            `- ${changeToolName(target.key)} only proposes; the card shows each record's value now and after. Never say a record was changed.`
+          ]
+        : [])
     ].join('\n'),
-    specs: [spec]
+    specs: [spec, ...changeSpecs(target, run)]
   }
 }
 

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

@@ -0,0 +1,209 @@
+/*
+ * Changing records that exist - the 수정안 (operato-application/design/ai/data-entry.md §5-1).
+ *
+ * The most expensive mistake is changing the wrong record, so which record is meant is settled here, by the
+ * server, never by the model's memory. A record is picked by the screen (the one being looked at, the rows
+ * selected) or by an id the find tool handed back; whichever way, it is read again through the application's
+ * read query as the person, and a record they cannot see is not found. The card shows what is there now and
+ * what it becomes; pressing reads it once more, and a field that moved in between keeps its row out.
+ *
+ * Pure but for the GraphQL runner, which comes in as an argument - the rules are tested without a server.
+ */
+import {
+  changeToolName,
+  findToolName,
+  readFieldValue,
+  sameFieldValue,
+  type EntryField,
+  type EntryIssue,
+  type EntryRecord,
+  type EntryTarget
+} from './entry-target.js'
+
+/** Runs one of the application's queries or mutations as the person. */
+export type GraphqlRunner = (document: string, variables: Record<string, unknown>) => Promise<{ data?: any; errors?: readonly { message: string }[] }>
+
+/** How the record of a change was picked - said on the card, so the person sees the ground of it. */
+export type ChangeVia = 'current' | 'selected' | 'id'
+
+export interface ChangeRow {
+  index: number
+  id: string
+  via: ChangeVia
+  label?: string
+  /** What the record holds now, for the fields that change - read by the server. */
+  before: Record<string, unknown>
+  values: Record<string, unknown>
+  issues: EntryIssue[]
+}
+
+export const MAX_CHANGES = 100
+
+const blockedChange = (row: { issues: EntryIssue[] }) => row.issues.some(issue => issue.blocking)
+
+/** The fields a target lets change. */
+export function changeableFields(target: EntryTarget): EntryField[] {
+  const names = target.update?.fields
+  return names ? target.fields.filter(field => names.includes(field.name)) : target.fields
+}
+
+/**
+ * The records the changes name. `current` is the record on screen, `selected` every row selected there -
+ * both from the surface's host context, which is **not trusted**: an id from it is only a candidate, read
+ * through the application before anything is shown. Any other ref is an id, from the find tool.
+ */
+export function resolveChangeRefs(
+  targetKey: string,
+  changes: unknown,
+  host: Record<string, any> | undefined
+): { picked: { id: string; via: ChangeVia; values: Record<string, unknown> }[]; unresolved: string[] } {
+  const picked: { id: string; via: ChangeVia; values: Record<string, unknown> }[] = []
+  const unresolved: string[] = []
+  const mine = (one: any) => !one?.target || one.target === targetKey
+  for (const change of Array.isArray(changes) ? changes : []) {
+    const values = change?.values && typeof change.values === 'object' ? change.values : {}
+    const ref = typeof change?.ref === 'string' ? change.ref.trim() : ''
+    if (ref === 'current') {
+      const id = mine(host?.record) ? host?.record?.id : undefined
+      if (typeof id === 'string' && id) picked.push({ id, via: 'current', values })
+      else unresolved.push('current')
+    } else if (ref === 'selected') {
+      const ids = mine(host?.selection) && Array.isArray(host?.selection?.ids) ? host!.selection.ids.filter((id: unknown) => typeof id === 'string' && id) : []
+      if (ids.length) for (const id of ids) picked.push({ id, via: 'selected', values })
+      else unresolved.push('selected')
+    } else if (ref) {
+      picked.push({ id: ref, via: 'id', values })
+    } else {
+      unresolved.push('no-ref')
+    }
+  }
+  return { picked: picked.slice(0, MAX_CHANGES), unresolved }
+}
+
+/** Reads the records by id through the application's read query, as the person. */
+export async function readRecords(target: EntryTarget, ids: string[], run: GraphqlRunner): Promise<Map<string, EntryRecord>> {
+  const update = target.update!
+  const answer = await run(update.read.query, update.read.variables([...new Set(ids)]))
+  if (answer.errors?.length) throw new Error(answer.errors.map(one => one.message).join('; '))
+  return new Map((update.read.recordsOf(answer.data) ?? []).filter(record => record && typeof record.id === 'string').map(record => [record.id, record]))
+}
+
+/** The change rows against what the records hold now. */
+export function changeRows(target: EntryTarget, picked: { id: string; via: ChangeVia; values: Record<string, unknown> }[], records: Map<string, EntryRecord>): ChangeRow[] {
+  const fields = new Map(changeableFields(target).map(field => [field.name, field]))
+  return picked.map((one, index): ChangeRow => {
+    const record = records.get(one.id)
+    const issues: EntryIssue[] = []
+    const values: Record<string, unknown> = {}
+    const before: Record<string, unknown> = {}
+    for (const [name, value] of Object.entries(one.values)) {
+      const field = fields.get(name)
+      if (!field) {
+        issues.push({ field: name, code: 'not-changeable', blocking: false })
+        continue
+      }
+      const { read, code } = value === null || value === '' ? { read: null, code: undefined } : readFieldValue(field, value)
+      if (read === undefined) {
+        values[name] = value
+        issues.push({ field: name, code: code!, params: code === 'not-in-list' ? { values: field.values } : undefined, blocking: true })
+      } else {
+        if (read === null && field.required) issues.push({ field: name, code: 'required', blocking: true })
+        values[name] = read
+      }
+      if (record) before[name] = record[name] ?? null
+    }
+    if (!record) issues.push({ code: 'record-not-found', blocking: true })
+    else if (Object.keys(values).length && Object.keys(values).every(name => sameFieldValue(fields.get(name)!, before[name], values[name])))
+      issues.push({ code: 'no-change', blocking: true })
+    if (!Object.keys(values).length && !issues.some(issue => issue.blocking)) issues.push({ code: 'nothing-to-change', blocking: true })
+    return { index, id: one.id, via: one.via, ...(record && target.update?.labelOf ? { label: target.update.labelOf(record) } : {}), before, values, issues }
+  })
+}
+
+/** What the card needs besides the rows - the fields that change, in the target's order. */
+function changedColumns(target: EntryTarget, rows: ChangeRow[]) {
+  const used = new Set(rows.flatMap(row => Object.keys(row.values)))
+  return changeableFields(target)
+    .filter(field => used.has(field.name))
+    .map(field => ({ name: field.name, type: field.type, ...(field.labelKey ? { labelKey: field.labelKey } : {}) }))
+}
+
+export async function proposeChanges(target: EntryTarget, args: any, context: any, run: GraphqlRunner) {
+  const { picked, unresolved } = resolveChangeRefs(target.key, args?.changes, context?.host)
+  if (!picked.length) {
+    return {
+      rejected: true,
+      error: unresolved.length ? `unresolved-${unresolved[0]}` : 'no-changes',
+      message:
+        unresolved[0] === 'current' || unresolved[0] === 'selected'
+          ? `the screen names no ${unresolved[0] === 'current' ? 'record' : 'selected rows'} of this kind. Ask the person which record, or call ${findToolName(target.key)}.`
+          : `name each record: ref "current", "selected", or an id from ${findToolName(target.key)}. Never guess an id.`
+    }
+  }
+  let records: Map<string, EntryRecord>
+  try {
+    records = await readRecords(target, picked.map(one => one.id), run)
+  } catch (error: any) {
+    return { rejected: true, error: 'read-failed', message: `could not read the records: ${error?.message ?? error}` }
+  }
+  const rows = changeRows(target, picked, records)
+  const blocked = rows.filter(blockedChange).length
+  return {
+    proposed: true,
+    kind: 'entry',
+    op: 'update',
+    target: target.key,
+    labelKey: target.labelKey,
+    label: `${rows.length} ${target.key} changes`,
+    icon: 'edit_note',
+    columns: changedColumns(target, rows),
+    rows,
+    counts: { rows: rows.length, ready: rows.length - blocked, blocked, cut: 0 },
+    ...(typeof args?.note === 'string' && args.note.trim() ? { reason: args.note.trim().slice(0, 300) } : {}),
+    message:
+      `proposed ${rows.length} changes (${rows.length - blocked} ready, ${blocked} blocked). Nothing changes until the person presses the card. ` +
+      'Tell them which records are not found or would not change.'
+  }
+}
+
+export const MAX_CANDIDATES = 20
+
+/** Candidates for what the person described - the model lists them and asks when there is more than one. */
+export async function findRecords(target: EntryTarget, args: any, run: GraphqlRunner) {
+  const find = target.update?.find
+  if (!find) return { rejected: true, error: 'no-find', message: 'this record cannot be searched.' }
+  const criteria: Record<string, unknown> = {}
+  for (const field of find.criteria) {
+    const value = args?.[field.name]
+    if (value === undefined || value === null || value === '') continue
+    const { read } = readFieldValue(field, value)
+    if (read !== undefined) criteria[field.name] = read
+  }
+  const answer = await run(find.query, find.variables(criteria))
+  if (answer.errors?.length) return { rejected: true, error: 'find-failed', message: answer.errors.map(one => one.message).join('; ') }
+  const found = (find.recordsOf(answer.data) ?? []).filter(record => record && typeof record.id === 'string')
+  return {
+    total: found.length,
+    candidates: found.slice(0, MAX_CANDIDATES).map(record => ({ id: record.id, ...(target.update?.labelOf ? { label: target.update.labelOf(record) } : {}), record })),
+    message:
+      found.length === 1
+        ? `one record matches; pass its id to ${changeToolName(target.key)}.`
+        : found.length
+          ? `${found.length} records match${found.length > MAX_CANDIDATES ? ` (first ${MAX_CANDIDATES} shown)` : ''}. List them to the person and ask which - never pick one yourself.`
+          : 'no record matches. Tell the person and ask for more to go on.'
+  }
+}
+
+/**
+ * The rows of a pressed 수정안, against what the records hold now. A row whose field moved since the card was
+ * made is kept out as `changed-since` - it is not overwritten unseen.
+ */
+export function stillAsProposed(target: EntryTarget, rows: ChangeRow[], now: Map<string, EntryRecord>): (ChangeRow & { now?: EntryRecord })[] {
+  const fields = new Map(target.fields.map(field => [field.name, field]))
+  return rows.map(row => {
+    const record = now.get(row.id)
+    if (!record) return { ...row, issues: [...row.issues, { code: 'record-not-found', blocking: true }] }
+    const moved = Object.keys(row.values).find(name => fields.get(name) && !sameFieldValue(fields.get(name)!, record[name] ?? null, row.before[name]))
+    return moved ? { ...row, now: record, issues: [...row.issues, { field: moved, code: 'changed-since', blocking: true }] } : { ...row, now: record }
+  })
+}

package/server/service/index.ts

@@ -11,6 +11,7 @@ import './chat-session/attachment-tools.js'
 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'
 
 export * from './types.js'
 export * from './chat-session-resolver.js'
@@ -27,6 +28,8 @@ export * from './tool-access.js'
 /* Data entry from material - an app registers what it can enter; a mode names it (design/ai/data-entry.md). */
 export * from './data-entry/entry-target.js'
 export { registerEntryTarget, entryCategoryOf } from './data-entry/entry-tools.js'
+/* The AI 작업판 - large results on a page of their own (design/ai/workspace.md). */
+export * from './workspace/workspace-blocks.js'
 /* 무엇이 근거인가 — 도구 결과 밖의 셋(프롬프트 · 대화 · 화면 스냅숏). */
 export * from './grounding-sources.js'
 /* 앵커 순수 로직 — 호스트가 앵커 종류를 참조한다(리졸버는 데코레이터 때문에 무겁다). */

package/server/service/workspace/workspace-blocks.ts

@@ -0,0 +1,127 @@
+/*
+ * The AI 작업판 - what a workspace is made of (operato-application/design/ai/workspace.md §3).
+ *
+ * The model does not write HTML. A workspace is a list of blocks of known kinds; the screen draws each, so
+ * theme, language and accessibility are the framework's. A block that does not fit is not dropped: it is
+ * kept as a fact in its place ("a block that cannot be drawn"), so the person sees that something was meant
+ * to be there. Pure - tested without a server.
+ */
+
+export const WORKSPACE_BLOCK_KINDS = ['heading', 'text', 'metrics', 'table', 'chart', 'steps'] as const
+export type WorkspaceBlockKind = (typeof WORKSPACE_BLOCK_KINDS)[number]
+
+export const MAX_BLOCKS = 40
+export const MAX_TABLE_ROWS = 1000
+export const MAX_SERIES = 8
+const MAX_TEXT = 20_000
+
+export interface WorkspaceBlock {
+  kind: WorkspaceBlockKind | 'unreadable'
+  [key: string]: unknown
+}
+
+export interface Workspace {
+  name: string
+  title: string
+  summary?: string
+  blocks: WorkspaceBlock[]
+}
+
+const text = (value: unknown, max = 500): string | undefined => (typeof value === 'string' && value.trim() ? value.trim().slice(0, max) : undefined)
+const scalar = (value: unknown): string | number | boolean | null =>
+  value === null || value === undefined ? null : typeof value === 'number' || typeof value === 'boolean' ? value : String(value).slice(0, 500)
+
+/** A short key of the workspace - the same name in one conversation is the same workspace, a new version. */
+export function workspaceName(name: unknown, title: string): string {
+  const given = typeof name === 'string' ? name.trim().toLowerCase() : ''
+  if (/^[a-z0-9][a-z0-9-]{0,63}$/.test(given)) return given
+  const slug = (given || title)
+    .toLowerCase()
+    .replace(/[^a-z0-9가-힣]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64)
+  return slug || 'workspace'
+}
+
+function unreadable(kind: unknown, reason: string): WorkspaceBlock {
+  return { kind: 'unreadable', was: typeof kind === 'string' ? kind.slice(0, 40) : null, reason }
+}
+
+function block(raw: any): WorkspaceBlock {
+  const kind = raw?.kind
+  switch (kind) {
+    case 'heading': {
+      const value = text(raw.text, 200)
+      if (!value) return unreadable(kind, 'no-text')
+      const level = [1, 2, 3].includes(raw.level) ? raw.level : 2
+      return { kind, text: value, level }
+    }
+    case 'text': {
+      const value = text(raw.markdown ?? raw.text, MAX_TEXT)
+      return value ? { kind, markdown: value } : unreadable(kind, 'no-text')
+    }
+    case 'metrics': {
+      const items = (Array.isArray(raw.items) ? raw.items : [])
+        .filter((one: any) => text(one?.label) && one?.value !== undefined && one?.value !== null)
+        .slice(0, 12)
+        .map((one: any) => ({ label: text(one.label, 80), value: scalar(one.value), ...(text(one.unit, 20) ? { unit: text(one.unit, 20) } : {}), ...(text(one.note, 200) ? { note: text(one.note, 200) } : {}) }))
+      return items.length ? { kind, items } : unreadable(kind, 'no-items')
+    }
+    case 'table': {
+      const columns = (Array.isArray(raw.columns) ? raw.columns : [])
+        .filter((one: any) => text(one?.name, 80))
+        .slice(0, 30)
+        .map((one: any) => ({ name: text(one.name, 80)!, ...(text(one.label, 80) ? { label: text(one.label, 80) } : {}), type: ['number', 'date', 'string'].includes(one.type) ? one.type : 'string' }))
+      if (!columns.length) return unreadable(kind, 'no-columns')
+      const given = Array.isArray(raw.rows) ? raw.rows : []
+      /* A row is an object by column name, or an array in column order - models write both. */
+      const rows = given.slice(0, MAX_TABLE_ROWS).map((row: any) =>
+        Object.fromEntries(columns.map((column: any, i: number) => [column.name, scalar(Array.isArray(row) ? row[i] : row?.[column.name])]))
+      )
+      return { kind, columns, rows, ...(text(raw.caption, 300) ? { caption: text(raw.caption, 300) } : {}), ...(given.length > MAX_TABLE_ROWS ? { cut: given.length - MAX_TABLE_ROWS } : {}) }
+    }
+    case 'chart': {
+      const x = (Array.isArray(raw.x) ? raw.x : []).slice(0, 200).map((one: unknown) => String(one ?? '').slice(0, 60))
+      const series = (Array.isArray(raw.series) ? raw.series : [])
+        .filter((one: any) => text(one?.name, 60) && Array.isArray(one?.values))
+        .map((one: any) => ({ name: text(one.name, 60)!, values: x.map((_: unknown, i: number) => (typeof one.values[i] === 'number' && Number.isFinite(one.values[i]) ? one.values[i] : null)) }))
+      if (!x.length || !series.length) return unreadable(kind, 'no-series')
+      /* Never a ninth hue: past eight, the first seven stay and the rest fold into one "other". */
+      const shown =
+        series.length > MAX_SERIES
+          ? [
+              ...series.slice(0, MAX_SERIES - 1),
+              { name: 'other', other: true, values: x.map((_: unknown, i: number) => series.slice(MAX_SERIES - 1).reduce((acc: number, one: any) => acc + (one.values[i] ?? 0), 0)) }
+            ]
+          : series
+      return { kind, chart: raw.chart === 'line' || raw.type === 'line' || raw.shape === 'line' ? 'line' : 'bar', x, series: shown, ...(text(raw.unit, 20) ? { unit: text(raw.unit, 20) } : {}), ...(text(raw.caption, 300) ? { caption: text(raw.caption, 300) } : {}) }
+    }
+    case 'steps': {
+      const items = (Array.isArray(raw.items) ? raw.items : [])
+        .filter((one: any) => text(one?.label, 200))
+        .slice(0, 50)
+        .map((one: any) => ({ label: text(one.label, 200), state: ['done', 'doing', 'todo', 'failed'].includes(one.state) ? one.state : 'todo', ...(text(one.note, 300) ? { note: text(one.note, 300) } : {}) }))
+      return items.length ? { kind, items } : unreadable(kind, 'no-items')
+    }
+    default:
+      return unreadable(kind, 'unknown-kind')
+  }
+}
+
+/** The workspace as the screen reads it. */
+export function normalizeWorkspace(args: any): { workspace?: Workspace; error?: string } {
+  const title = text(args?.title, 200)
+  if (!title) return { error: 'no-title' }
+  const given = Array.isArray(args?.blocks) ? args.blocks : []
+  if (!given.length) return { error: 'no-blocks' }
+  const blocks = given.slice(0, MAX_BLOCKS).map(block)
+  if (given.length > MAX_BLOCKS) blocks.push({ kind: 'unreadable', was: null, reason: 'too-many-blocks', cut: given.length - MAX_BLOCKS })
+  return { workspace: { name: workspaceName(args?.name, title), title, ...(text(args?.summary, 500) ? { summary: text(args.summary, 500) } : {}), blocks } }
+}
+
+/** One line of what is in it - for the card in the conversation and for the model. */
+export function workspaceContents(workspace: Workspace): Record<string, number> {
+  const counts: Record<string, number> = {}
+  for (const one of workspace.blocks) if (['table', 'chart', 'metrics', 'steps'].includes(one.kind)) counts[one.kind] = (counts[one.kind] ?? 0) + 1
+  return counts
+}

package/server/service/workspace/workspace-tools.ts

@@ -0,0 +1,66 @@
+/*
+ * showInWorkspace - the model puts a large result on the AI 작업판 (operato-application/design/ai/workspace.md §5).
+ *
+ * The result rides on the answer as a proposal of kind 'workspace', so the conversation's gates hold for it:
+ * who may read the conversation reads the workspace, and a value behind a door the reader cannot pass hides
+ * it with the answer (ADR-0073). The tool itself reaches no door - what it carries came from the turn's other
+ * tools, whose doors the answer row collects.
+ */
+import { registerToolCategory, type ToolCategory, type ToolSpec } from '@things-factory/ai-client-base'
+
+import { normalizeWorkspace, workspaceContents, WORKSPACE_BLOCK_KINDS } from './workspace-blocks.js'
+
+export const WORKSPACE_CATEGORY = 'assistant-workspace'
+
+export function showInWorkspace(args: any) {
+  const { workspace, error } = normalizeWorkspace(args)
+  if (!workspace) return { rejected: true, error, message: 'a workspace needs a title and at least one block.' }
+  const contents = workspaceContents(workspace)
+  return {
+    proposed: true,
+    kind: 'workspace',
+    icon: 'dashboard',
+    label: workspace.title,
+    workspace,
+    contents,
+    message: `put "${workspace.title}" on the workspace (${workspace.blocks.length} blocks). The person opens it from the card - say in one line what it holds; do not repeat its tables in the answer.`
+  }
+}
+
+const spec = {
+  kind: 'read',
+  name: 'showInWorkspace',
+  doors: [],
+  description:
+    'Put a large result on the AI workspace - a page the person opens from a card, beside the conversation. Blocks: ' +
+    'heading{text,level}, text{markdown}, metrics{items:[{label,value,unit,note}]}, table{columns:[{name,label,type:number|date|string}],rows,caption}, ' +
+    'chart{chart:bar|line, x:[labels], series:[{name,values:[numbers]}], unit, caption}, steps{items:[{label,state:done|doing|todo|failed,note}]}.',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: 'A short key, lowercase with dashes ("contracts-by-customer"). The same name again makes a new version of the same workspace.' },
+      title: { type: 'string' },
+      summary: { type: 'string', description: 'One line under the title.' },
+      blocks: {
+        type: 'array',
+        items: { type: 'object', properties: { kind: { type: 'string', enum: [...WORKSPACE_BLOCK_KINDS] } }, required: ['kind'] }
+      }
+    },
+    required: ['name', 'title', 'blocks']
+  },
+  builder: (args: any) => showInWorkspace(args)
+} as ToolSpec
+
+export const workspaceCategory: ToolCategory = {
+  name: WORKSPACE_CATEGORY,
+  description: 'the AI workspace - a page for results too large for the conversation',
+  guidance: [
+    '- When a result is more than a short table (over 20 rows, or two or more tables or charts), or the person asks for a page, call showInWorkspace. Keep the answer short: the point, and that it is on the workspace.',
+    '- Every number in a block comes from a tool result in this conversation - never computed or guessed by you.',
+    '- To change a workspace, call showInWorkspace again with the same name and the whole new content; it becomes a new version.',
+    '- Never say something is on the workspace unless you called showInWorkspace in this turn.'
+  ].join('\n'),
+  specs: [spec]
+}
+
+registerToolCategory(workspaceCategory)

package/server/service/workspace/workspace.test.ts

@@ -0,0 +1,58 @@
+/*
+ * The AI 작업판 (design/ai/workspace.md) - what a block may be, what happens to one that is not, and what the
+ * tool hands back.
+ */
+import { normalizeWorkspace, workspaceName, MAX_SERIES } from './workspace-blocks'
+import { showInWorkspace, workspaceCategory } from './workspace-tools'
+
+describe('the workspace', () => {
+  it('★ is blocks of known kinds - a block that does not fit stays in its place as a fact, never dropped silently', () => {
+    const { workspace } = normalizeWorkspace({
+      name: 'contracts',
+      title: '2026 contracts',
+      blocks: [{ kind: 'heading', text: 'By customer' }, { kind: 'html', html: '<script>x</script>' }, { kind: 'table', rows: [] }]
+    })
+    expect(workspace!.blocks).toEqual([
+      { kind: 'heading', text: 'By customer', level: 2 },
+      { kind: 'unreadable', was: 'html', reason: 'unknown-kind' },
+      { kind: 'unreadable', was: 'table', reason: 'no-columns' }
+    ])
+  })
+
+  it('reads a table row as an object by column or an array in column order, and cuts at the limit saying how many', () => {
+    const rows = [{ customer: 'A', amount: 10 }, ['B', 20], ...Array.from({ length: 1000 }, () => ({ customer: 'x', amount: 1 }))]
+    const table: any = normalizeWorkspace({ title: 't', blocks: [{ kind: 'table', columns: [{ name: 'customer' }, { name: 'amount', type: 'number' }], rows }] }).workspace!.blocks[0]
+    expect(table.rows.slice(0, 2)).toEqual([{ customer: 'A', amount: 10 }, { customer: 'B', amount: 20 }])
+    expect(table.rows).toHaveLength(1000)
+    expect(table.cut).toBe(2)
+  })
+
+  it('★ a chart never gets a ninth colour - past eight series the rest fold into "other"', () => {
+    const series = Array.from({ length: 10 }, (_, i) => ({ name: `s${i}`, values: [1, 2] }))
+    const chart: any = normalizeWorkspace({ title: 't', blocks: [{ kind: 'chart', x: ['Jan', 'Feb'], series }] }).workspace!.blocks[0]
+    expect(chart.series).toHaveLength(MAX_SERIES)
+    expect(chart.series[MAX_SERIES - 1]).toEqual({ name: 'other', other: true, values: [3, 6] })
+    expect(chart.chart).toBe('bar')
+  })
+
+  it('a value that is not a number is a gap in the chart, never a zero', () => {
+    const chart: any = normalizeWorkspace({ title: 't', blocks: [{ kind: 'chart', chart: 'line', x: ['a', 'b', 'c'], series: [{ name: 'n', values: [1, 'x', 3] }] }] }).workspace!.blocks[0]
+    expect(chart.series[0].values).toEqual([1, null, 3])
+  })
+
+  it('the same name is the same workspace - a name that is not a key is made one from it', () => {
+    expect(workspaceName('contracts-by-customer', 'x')).toBe('contracts-by-customer')
+    expect(workspaceName(undefined, '2026 Contracts / 고객사')).toBe('2026-contracts-고객사')
+  })
+
+  it('★ the tool hands back a proposal of kind workspace, so the answer row carries it - and the conversation gates it', () => {
+    const result: any = showInWorkspace({ name: 'c', title: 'Contracts', blocks: [{ kind: 'table', columns: [{ name: 'a' }], rows: [[1]] }, { kind: 'metrics', items: [{ label: 'n', value: 26 }] }] })
+    expect(result).toMatchObject({ proposed: true, kind: 'workspace', label: 'Contracts', contents: { table: 1, metrics: 1 } })
+    expect((workspaceCategory.specs[0] as any).doors).toEqual([])
+  })
+
+  it('no title or no blocks is refused, with what it needs', () => {
+    expect(showInWorkspace({ blocks: [{ kind: 'text', markdown: 'x' }] })).toMatchObject({ rejected: true, error: 'no-title' })
+    expect(showInWorkspace({ title: 'x', blocks: [] })).toMatchObject({ rejected: true, error: 'no-blocks' })
+  })
+})

package/test/entry-proposal.test.ts

@@ -7,6 +7,7 @@ import { join } from 'path'
 
 import { runProposal, setEntryProposalHandler } from '../client/utils/assistant-proposals'
 import {
+  entryGroupOf,
   entryOutcomeNote,
   entryProposalHandler,
   entryReadyCount,
@@ -31,8 +32,8 @@ describe('the entry card', () => {
 
   it('★ the newest card per record is the current one - an older one is replaced', () => {
     const latest = latestEntryKeys([[card('k1')], [{ key: 'x', tool: 'proposeAction' }], [card('k2'), card('k3', 'office.leave')]])
-    expect(latest.get('office.expense-line')).toBe('k2')
-    expect(latest.get('office.leave')).toBe('k3')
+    expect(latest.get('office.expense-line:create')).toBe('k2')
+    expect(latest.get('office.leave:create')).toBe('k3')
   })
 
   it('leaves in the conversation what went in and each row that did not, by its place', () => {
@@ -64,4 +65,16 @@ describe('the entry card', () => {
     expect(chat).toContain("'ai-assistant.entry.enter'")
     expect(chat).toContain("'ai-assistant.entry.replaced'")
   })
+
+  it('★ a 입력안 and a 수정안 of one record are counted apart - a newer 수정안 replaces only the older 수정안', () => {
+    const latest = latestEntryKeys([[card('e1')], [{ ...card('u1'), op: 'update' }], [card('e2')]])
+    expect(latest.get(entryGroupOf(card('x')))).toBe('e2')
+    expect(latest.get(entryGroupOf({ ...card('x'), op: 'update' }))).toBe('u1')
+  })
+
+  it('a 수정안 says in the conversation what was changed', () => {
+    expect(entryOutcomeNote({ verdict: 'accepted', applied: 1, missed: 1, op: 'update', rows: [{ index: 0, ok: true }, { index: 1, ok: false, error: 'amount: changed-since' }] }, t)).toBe(
+      'changed 1 records.\nrow 2: amount: changed-since'
+    )
+  })
 })