@things-factory/ai-client-base 10.1.53 → 10.1.114

package/experiments/entity360/run.cjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Synthetic-only pilot. Build the package first; never reads application databases or credentials from files.
+const { readFileSync, writeFileSync } = require('node:fs')
+const { join } = require('node:path')
+const { createServer } = require('node:http')
+const { recommendCandidate } = require('../../dist-server/service/decision/decision.js')
+const { createJevDecisionProvider } = require('../../dist-server/service/decision/jev.js')
+const expanded = process.argv.includes('--expanded')
+const apps = process.argv.includes('--apps')
+if (apps && expanded) throw new Error('Choose one evaluation suite')
+const fixtures = require(apps ? './apps.cjs' : expanded ? './expanded.cjs' : './fixtures.json')
+const live = process.argv.includes('--jev')
+const provider = live ? createJevDecisionProvider(process.env.TYPESAFE_API_KEY || '') : undefined
+const actionProvider = live ? createJevDecisionProvider(process.env.TYPESAFE_API_KEY || '', fetch, 'action') : undefined
+const mode = live ? 'Jev API · synthetic data' : 'Exact baseline · no external model'
+const operationalFailures = new Set(['provider-error', 'timeout', 'invalid-reply', 'invalid-input', 'stale-context', 'access-changed'])
+
+async function evaluate(testCase) {
+  const candidates = testCase.scenario ? fixtures.scenarios[testCase.scenario] : fixtures.candidates
+  const result = await recommendCandidate({
+    query: testCase.query, candidates,
+    mayRead: async c => candidates.some(f => f.key === c.key && !f.denied),
+    isCurrent: () => true, provider: testCase.purpose === 'action' ? actionProvider : provider, timeoutMs: 300
+  })
+  // An outage must never count as a correct semantic abstention.
+  return { ...testCase, result, correct: !operationalFailures.has(result.reason) && (result.candidateKey ?? null) === testCase.expected }
+}
+
+function metrics(rows) {
+  const selected = rows.filter(r => r.result.status === 'suggested')
+  const durations = rows.map(r => r.result.elapsedMs).sort((a, b) => a - b)
+  return {
+    mode, synthetic: true, cases: rows.length,
+    correctIncludingAbstentions: rows.filter(r => r.correct).length,
+    suggestions: selected.length, wrongSuggestions: selected.filter(r => !r.correct).length,
+    expectedResolvable: rows.filter(r => r.expected).length,
+    correctAbstentions: rows.filter(r => !r.expected && r.correct).length,
+    missedResolvable: rows.filter(r => r.expected && r.result.status === 'abstained').length,
+    errorsOrTimeouts: rows.filter(r => operationalFailures.has(r.result.reason)).length,
+    p50Ms: durations[Math.ceil(durations.length * 0.5) - 1],
+    p95Ms: durations[Math.ceil(durations.length * 0.95) - 1],
+    note: 'Synthetic fixtures on a fixed shortlist; single sequential run, not a production benchmark. Thresholds are uncalibrated.'
+  }
+}
+
+async function main() {
+  if (!process.argv.includes('--serve')) {
+    const rows = []
+    for (const c of fixtures.cases) rows.push(await evaluate(c))
+    const families = [...new Set(rows.map(r => r.baseId || r.id))].map(id => rows.filter(r => (r.baseId || r.id) === id))
+    const report = { measuredAt: new Date().toISOString(), metrics: metrics(rows), orderConsistency: {
+      logicalCases: families.length,
+      sameOutcomeAcrossVariants: families.filter(list => new Set(list.map(r => operationalFailures.has(r.result.reason) ? r.result.reason : r.result.candidateKey ?? null)).size === 1).length,
+      allVariantsCorrect: families.filter(list => list.every(r => r.correct)).length
+    }, groups: Object.fromEntries(
+      [...new Set(rows.map(r => r.group))].map(group => [group, metrics(rows.filter(r => r.group === group))])
+    ), rows }
+    if (process.argv.includes('--report')) {
+      writeFileSync(join(__dirname, `${live ? 'jev' : 'baseline'}${apps ? '-apps' : expanded ? '-expanded' : ''}-results.json`), JSON.stringify(report, null, 2) + '\n')
+    }
+    console.log(JSON.stringify(process.argv.includes('--summary')
+      ? { measuredAt: report.measuredAt, metrics: report.metrics, orderConsistency: report.orderConsistency,
+          failures: rows.filter(r => !r.correct).map(r => ({ id: r.id, query: r.query, expected: r.expected, actual: r.result.candidateKey ?? null, reason: r.result.reason })) }
+      : report, null, 2))
+    return
+  }
+  const server = createServer(async (req, res) => {
+    const origin = `http://${req.headers.host}`
+    res.setHeader('Cache-Control', 'no-store')
+    res.setHeader('X-Content-Type-Options', 'nosniff')
+    if (req.headers.host !== `127.0.0.1:${server.address().port}` || (req.headers.origin && req.headers.origin !== origin)) {
+      res.writeHead(403).end(); return
+    }
+    if (req.method === 'GET' && req.url === '/') {
+      res.setHeader('Content-Type', 'text/html; charset=utf-8')
+      res.end(readFileSync(join(__dirname, 'index.html'))); return
+    }
+    if (req.method === 'GET' && req.url === '/fixtures') {
+      res.setHeader('Content-Type', 'application/json')
+      res.end(JSON.stringify({ mode, cases: fixtures.cases, candidates: fixtures.candidates.filter(c => !c.denied),
+        scenarios: Object.fromEntries(Object.entries(fixtures.scenarios).map(([key, values]) => [key, values.filter(c => !c.denied)])) })); return
+    }
+    if (req.method !== 'POST' || req.url !== '/evaluate' || req.headers['content-type'] !== 'application/json') {
+      res.writeHead(404).end(); return
+    }
+    try {
+      let body = ''
+      for await (const chunk of req) {
+        body += chunk
+        if (body.length > 1024) { res.writeHead(413).end(); return }
+      }
+      const testCase = fixtures.cases.find(c => c.id === JSON.parse(body).id)
+      if (!testCase) { res.writeHead(400).end(); return }
+      res.setHeader('Content-Type', 'application/json')
+      res.end(JSON.stringify(await evaluate(testCase)))
+    } catch { res.writeHead(500).end('Pilot evaluation failed') }
+  })
+  server.listen(0, '127.0.0.1', () => console.log(JSON.stringify({ url: `http://127.0.0.1:${server.address().port}`, mode })))
+}
+main().catch(() => { console.error('Pilot could not start. Build ai-client-base; --jev also requires TYPESAFE_API_KEY.'); process.exitCode = 1 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@things-factory/ai-client-base",
-  "version": "10.1.53",
+  "version": "10.1.114",
   "main": "dist-server/index.js",
   "things-factory": true,
   "author": "heartyoh",
@@ -27,5 +27,5 @@
     "@things-factory/env": "^10.1.20",
     "openai": "^4.0.0"
   },
-  "gitHead": "1bdb0c604614735fd5a5467aee1e56f53be6b89e"
+  "gitHead": "0d8f9bc0ff0cb50431f2c76cb166aaf3809d3cf7"
 }

package/server/service/agentic-loop/agentic-loop.test.ts

@@ -917,3 +917,126 @@ describe('runAgenticLoop — 같은 조치는 한 번만 제안된다', () => {
     expect(r.proposals).toHaveLength(2)
   })
 })
+
+describe('a read tool that hands back a picture (design/ai/shared-dock.md §9-4)', () => {
+  const png = Buffer.from([0x89, 0x50, 0x4e, 0x47, 1, 2, 3])
+
+  test('★ the picture rides as an image part after the results - never in the JSON, the grounding or the usage', async () => {
+    const sent: any[][] = []
+    let turn = 0
+    const input = mkInput(
+      {
+        chat: async (conversation: any) => {
+          sent.push(conversation)
+          return turn++ === 0 ? okResult(undefined, [TC('readChatAttachment', { attachmentId: 'a1' })]) : okResult('영수증 금액은 12,400원입니다')
+        }
+      },
+      {
+        isReadTool: name => name === 'readChatAttachment',
+        executeReadTool: () => ({ attachmentId: 'a1', type: 'image', images: [{ data: png, mediaType: 'image/png' }] })
+      }
+    )
+    const r = await runAgenticLoop(input)
+    const last = sent[1][sent[1].length - 1]
+    expect(last.role).toBe('user')
+    expect(last.content.map((part: any) => part.type)).toEqual(['tool_result', 'image'])
+    expect(last.content[1].source).toEqual({ kind: 'base64', data: png, mediaType: 'image/png' })
+    expect(JSON.parse(last.content[0].content)).toEqual({ attachmentId: 'a1', type: 'image', imagesAttached: 1 })
+    expect(JSON.stringify(r.groundedTexts)).not.toContain('"images":')
+    expect(JSON.stringify(r.groundedTexts)).not.toContain('mediaType')
+    expect(JSON.stringify(r.toolUsages)).not.toContain('"images":')
+  })
+
+  test('a picture of a type every provider does not take, or with no bytes, is left out and said', async () => {
+    const { takeToolImages } = await import('./agentic-loop')
+    const { value, images } = takeToolImages({ images: [{ data: png, mediaType: 'image/tiff' }, { data: Buffer.alloc(0), mediaType: 'image/png' }, { data: png.toString('base64'), mediaType: 'IMAGE/JPEG' }] })
+    expect(images.map(one => (one.source as any).mediaType)).toEqual(['image/jpeg'])
+    expect(value).toEqual({ imagesAttached: 1, imagesLeftOut: 2 })
+    expect(takeToolImages({ text: 'a' })).toEqual({ value: { text: 'a' }, images: [] })
+  })
+
+  test('★ OpenAI - the tool messages first, then the pictures as one user message (a tool message holds text only)', async () => {
+    const { toSDKMessages } = await import('../providers/openai')
+    const messages = toSDKMessages({
+      role: 'user',
+      content: [
+        { type: 'tool_result', toolUseId: 'c1', content: '{"imagesAttached":1}' },
+        { type: 'image', source: { kind: 'base64', data: png, mediaType: 'image/png' } }
+      ]
+    } as any)
+    expect(messages.map((one: any) => one.role)).toEqual(['tool', 'user'])
+    expect(messages[1].content[0]).toEqual({ type: 'image_url', image_url: { url: `data:image/png;base64,${png.toString('base64')}` } })
+  })
+})
+
+describe('what only the card needs (design/ai/read-targets.md §4)', () => {
+  test('★ a proposal\'s forScreen reaches the card, never the model', async () => {
+    const sent: any[][] = []
+    let turn = 0
+    const rows = Array.from({ length: 300 }, (_, i) => ({ amount: i }))
+    const input = mkInput(
+      {
+        chat: async (conversation: any) => {
+          sent.push(conversation)
+          return turn++ === 0 ? okResult(undefined, [TC('queryOfficeCashTransaction')]) : okResult('300건입니다')
+        }
+      },
+      {
+        isReadTool: () => true,
+        executeReadTool: () => ({ proposed: true, kind: 'workspace', count: 300, forScreen: { workspace: { name: 'w', title: 't', blocks: [{ kind: 'table', rows }] } } })
+      }
+    )
+    const r = await runAgenticLoop(input)
+    const toModel = JSON.parse(sent[1][sent[1].length - 1].content[0].content)
+    expect(toModel).toEqual({ proposed: true, kind: 'workspace', count: 300 })
+    expect(r.proposals[0].workspace.blocks[0].rows).toHaveLength(300)
+    expect(JSON.stringify(r.toolUsages)).not.toContain('"forScreen"')
+  })
+
+  test('only a proposal carries it - a plain result keeps the field as it is', async () => {
+    const { takeForScreen } = await import('./agentic-loop')
+    expect(takeForScreen({ forScreen: { a: 1 } })).toEqual({ value: { forScreen: { a: 1 } }, forScreen: {} })
+  })
+})
+
+/*
+ * A tool that names its proposal keeps that name (2026-10-02, Figure and AI lanes): figure-service gives a UUID the
+ * modeller creates the new figure under, and the effect key written over it refused the run. Folding is by the effect
+ * key, kept apart as `effectKey`.
+ */
+describe('runAgenticLoop — a proposal keeps the name its tool gave it', () => {
+  const twice = (results: any[]) => {
+    let call = 0
+    return mkInput(
+      {
+        chat: async () => (++call <= results.length ? okResult(undefined, [TC('proposeFigureCandidate', {}, `t${call}`)]) : okResult('done'))
+      },
+      { isReadTool: () => true, executeReadTool: () => results[call - 1] }
+    )
+  }
+  const uuid = '3f1c2a9e-7b4d-4c1e-9a2f-5d6e7f8a9b0c'
+
+  test('the tool\'s key stays the key; the effect key goes beside it', async () => {
+    const r = await runAgenticLoop(twice([{ proposed: true, key: uuid, steps: [{ kind: 'rename', name: 'Bin' }] }]))
+    expect(r.proposals).toHaveLength(1)
+    expect(r.proposals[0].key).toBe(uuid)
+    expect(r.proposals[0].effectKey).toMatch(/^proposeFigureCandidate#/)
+  })
+
+  test('the same proposal twice, worded differently, is still one card', async () => {
+    const r = await runAgenticLoop(
+      twice([
+        { proposed: true, key: uuid, label: 'one', steps: [{ kind: 'rename', name: 'Bin' }] },
+        { proposed: true, key: uuid, label: 'two', steps: [{ kind: 'rename', name: 'Bin' }] }
+      ])
+    )
+    expect(r.proposals).toHaveLength(1)
+    expect(r.toolUsages.map((u: any) => u.outcome)).toEqual(['proposed', 'folded'])
+  })
+
+  test('a tool that gives no key gets the effect key, as before', async () => {
+    const r = await runAgenticLoop(twice([{ proposed: true, values: { capacity: 10 } }]))
+    expect(r.proposals[0].key).toBe(r.proposals[0].effectKey)
+    expect(r.proposals[0].key).toMatch(/^proposeFigureCandidate#/)
+  })
+})

package/server/service/agentic-loop/agentic-loop.ts

@@ -39,7 +39,7 @@
 import { createHash } from 'node:crypto'
 
 import debug from 'debug'
-import type { AIMessage, AIToolCall, AIToolChatResult } from '../types.js'
+import type { AIImageMediaType, AIImagePart, AIMessage, AIToolCall, AIToolChatResult } from '../types.js'
 import { retryTransient } from '../utils/index.js'
 
 const log = debug('things-factory:ai:agentic-loop')
@@ -534,13 +534,18 @@ async function processToolCalls<TCtx, TOp>(
   iter: number
 ): Promise<any[]> {
   const toolResultParts: any[] = []
+  const toolResultImages: AIImagePart[] = []
 
   for (const tc of toolCalls) {
     if (dispatch.isReadTool(tc.name)) {
       /* await 필수 — registry 에 등록된 read/external builder 는 async 일 수 있다(DB·외부 호출).
        * await 없이 JSON.stringify 하면 Promise 가 '{}' 로 직렬화되어 LLM 이 **빈 결과**를 받는다
        * (문서 가져오기·트윈 구조 조회 등 — 무엇인지는 부르는 쪽이 안다). */
-      const value = await dispatch.executeReadTool(tc, context)
+      /* Pictures a read tool hands back ride as image parts after the results - never inside the JSON. */
+      const { value: given, images } = takeToolImages(await dispatch.executeReadTool(tc, context))
+      toolResultImages.push(...images)
+      /* What only the card needs (a table of a thousand rows) goes to the screen, never to the model. */
+      const { value, forScreen } = takeForScreen(given)
       /* 제안 규약 — 결과가 `proposed: true` 면 조치 제안이다(도메인은 모른 채 그대로 실어 올린다).
        * 이 채널이 없으면 대화면은 도구 추적(trace)을 뒤져야 하고, 실행 버튼을 만들 근거가 없다. */
       /* 판정(outcome) — 화면이 단계별 배지로 보여줄 값. 조용한 무동작을 남기지 않는다. */
@@ -549,13 +554,22 @@ async function processToolCalls<TCtx, TOp>(
         /* **같은 조치는 한 번만** — 모델이 같은 것을 두 번 제안하는 일이 실제로 있었다(하나는 인자가
          * 비어 있었다). 카드가 둘이면 사용자가 같은 명령을 두 번 실행할 수 있고, 그건 되돌릴 수 없다.
          * 판정은 **효과**(도구·명령·대상·인자)로 한다 — 설명 문구(label·reason)가 달라도 같은 조치다. */
-        const candidate = { tool: tc.name, ...(value as any) }
-        const key = proposalEffectKey(candidate)
-        if (proposals.some(p => p.key === key)) {
+        const candidate = { tool: tc.name, ...(value as any), ...forScreen }
+        const effectKey = proposalEffectKey(candidate)
+        if (proposals.some(p => p.effectKey === effectKey)) {
           outcome = 'folded' // 접힌 사실을 남긴다 — "왜 카드가 하나뿐인가" 가 추적 가능해야 한다
         } else {
-          /* 키를 함께 실어 보낸다 — 카드가 같은 규칙으로 다시 세지 않게(원본은 하나). */
-          proposals.push({ ...candidate, key })
+          /*
+           * 키를 함께 실어 보낸다 — 카드가 같은 규칙으로 다시 세지 않게(원본은 하나).
+           *
+           * **도구가 이름을 준 제안은 그 이름을 쓴다**(2026-10-02, Figure 레인 · AI 레인 합의). figure-service 의
+           * 도구는 제안에 UUID `key` 를 붙이고, 모델러는 그 UUID 로 새 도형을 만든다(ADR-0097 5.6절 5항). 효과 키로
+           * 덮어쓰면 「제안 식별자가 올바르지 않습니다」로 실행이 막혔다. 같은 조치인지는 효과 키(`effectKey`)로
+           * 따로 판정하므로 접기는 그대로다. 도구 `key` 는 **한 대화 안에서 유일해야 한다** — 겹치면 입력안의 「새
+           * 카드가 옛 카드를 대신함」 판정과 결말 줄이 섞인다. 이름을 주지 않는 도구(ai-assistant 의 제안 도구들)는
+           * 지금처럼 효과 키를 받는다.
+           */
+          proposals.push({ ...candidate, key: typeof (candidate as any).key === 'string' && (candidate as any).key ? (candidate as any).key : effectKey, effectKey })
           outcome = 'proposed'
         }
       } else if (value && typeof value === 'object' && ((value as any).rejected === true || (value as any).error)) {
@@ -656,5 +670,49 @@ async function processToolCalls<TCtx, TOp>(
     }
   }
 
-  return toolResultParts
+  /* Every provider takes a picture after the results of the same turn (design/ai/shared-dock.md §9-4). */
+  return [...toolResultParts, ...toolResultImages]
+}
+
+/**
+ * A proposal's reserved `forScreen` field, taken out of what the model reads and kept for the card.
+ *
+ * A read tool that has queried many rows puts them on the card (the AI 작업판 table) but tells the model only the
+ * count, the totals and a few rows - the model does not copy a table it never received, so the card's numbers are
+ * the query's own (operato-application/design/ai/read-targets.md §4). Only a proposal (`proposed: true`) carries it.
+ */
+export function takeForScreen(result: any): { value: any; forScreen: Record<string, unknown> } {
+  if (!result || typeof result !== 'object' || Array.isArray(result) || result.proposed !== true || !result.forScreen || typeof result.forScreen !== 'object') {
+    return { value: result, forScreen: {} }
+  }
+  const { forScreen, ...value } = result
+  return { value, forScreen }
+}
+
+const TOOL_IMAGE_TYPES = ['image/png', 'image/jpeg', 'image/gif', 'image/webp']
+
+/**
+ * The pictures a read tool returned in its reserved `images` field, taken out of the result.
+ *
+ * A tool result reaches the model as JSON text; a picture cannot. So a read tool that must show one - a picture
+ * sent in an earlier turn of the conversation - returns `images: [{ data, mediaType }]`, and the loop sends each as an
+ * image part of the same turn. The bytes never stay in the JSON, the grounding texts or the usage record. A picture
+ * of a type the providers do not all take is left out and said in the result.
+ */
+export function takeToolImages(result: any): { value: any; images: AIImagePart[] } {
+  if (!result || typeof result !== 'object' || Array.isArray(result) || !Array.isArray(result.images)) return { value: result, images: [] }
+  const { images: given, ...value } = result
+  const images: AIImagePart[] = []
+  let left = 0
+  for (const one of given) {
+    const data = typeof one?.data === 'string' ? Buffer.from(one.data, 'base64') : one?.data
+    const mediaType = String(one?.mediaType ?? '').toLowerCase()
+    if ((Buffer.isBuffer(data) || data instanceof Uint8Array) && data.length && TOOL_IMAGE_TYPES.includes(mediaType)) {
+      images.push({ type: 'image', source: { kind: 'base64', data, mediaType: mediaType as AIImageMediaType } })
+    } else left++
+  }
+  return {
+    value: { ...value, imagesAttached: images.length, ...(left ? { imagesLeftOut: left } : {}) },
+    images
+  }
 }

package/server/service/decision/config.test.ts

@@ -0,0 +1,55 @@
+const mockGet = jest.fn()
+jest.mock('@things-factory/env', () => ({ config: { get: (...args: any[]) => mockGet(...args) } }))
+import { createConfiguredDecisionClient, getDefaultDecisionClient } from './config'
+
+beforeEach(() => mockGet.mockReset())
+
+test('absent and disabled config do not require a key or produce a client', () => {
+  expect(createConfiguredDecisionClient(null)).toBeUndefined()
+  expect(createConfiguredDecisionClient({ enabled: false })).toBeUndefined()
+})
+
+test('reads only aiDecision and exposes policy without exposing credentials', () => {
+  mockGet.mockReturnValue({ enabled: true, provider: 'typesafe', apiKey: 'test-credential' })
+  const client = getDefaultDecisionClient()!
+  expect(mockGet).toHaveBeenCalledWith('aiDecision', null)
+  expect(client.model).toBe('jev-1.13.0')
+  expect(client.timeoutMs).toBe(300)
+  expect(JSON.stringify(client)).not.toContain('test-credential')
+})
+
+test.each([
+  { enabled: 'true' }, { provider: 'unknown' }, { model: 'jev-latest' },
+  { timeoutMs: 0 }, { timeoutMs: NaN }, { timeoutMs: 10001 }, { apiKey: ' ' }
+])('invalid enabled config fails explicitly without logging supplied values', change => {
+  expect(() => createConfiguredDecisionClient({ enabled: true, provider: 'typesafe', apiKey: 'test-credential', ...change } as any)).toThrow(/^aiDecision\./)
+})
+
+test('configured deadline governs recommendation even if caller tries to override it', async () => {
+  const client = createConfiguredDecisionClient({ enabled: true, provider: 'typesafe', apiKey: 'test-credential', timeoutMs: 5 })!
+  const result = await client.recommend({
+    query: 'order', candidates: [{ key: '1', label: 'order', description: '' }],
+    mayRead: () => new Promise<boolean>(() => {}), isCurrent: () => true, timeoutMs: 10000
+  } as any)
+  expect(result.reason).toBe('timeout')
+  expect(result.provider).toBe('jev-1.13.0')
+})
+
+test('host explicitly selects action classification; default stays entity and unknown purpose fails closed', async () => {
+  const transport = jest.spyOn(globalThis, 'fetch').mockImplementation(async (_url, options) => {
+    const body = JSON.parse(options!.body as string)
+    const purpose = Object.keys(body.questions)[0]
+    return { ok: true, json: async () => ({ model: 'jev-1.13.0', answers: { [purpose]: {
+      type: 'choice', choice: 'read', confidence: 1, probabilities: { read: 1, __none__: 0 }
+    } } }) } as Response
+  })
+  try {
+    const client = createConfiguredDecisionClient({ enabled: true, provider: 'typesafe', apiKey: 'test-credential' })!
+    const request = { query: 'read', candidates: [{ key: 'read', label: 'read', description: 'Read only' }], mayRead: async () => true, isCurrent: () => true }
+    expect((await client.recommend({ ...request, purpose: 'action' })).candidateKey).toBe('read')
+    expect((await client.recommend(request)).candidateKey).toBe('read')
+    expect(transport.mock.calls.map(([, options]) => Object.keys(JSON.parse(options!.body as string).questions)[0])).toEqual(['action', 'entity'])
+    await expect(client.recommend({ ...request, purpose: 'other' as any })).rejects.toThrow('Unsupported decision purpose')
+    expect(transport).toHaveBeenCalledTimes(2)
+  } finally { transport.mockRestore() }
+})

package/server/service/decision/config.ts

@@ -0,0 +1,49 @@
+import { config as envConfig } from '@things-factory/env'
+import { recommendCandidate, type DecisionResult } from './decision'
+import { createJevDecisionProvider, JEV_DECISION_MODEL, type JevDecisionPurpose } from './jev'
+
+export interface AIDecisionConfig {
+  enabled: boolean
+  provider?: 'typesafe'
+  model?: string
+  apiKey?: string
+  timeoutMs?: number
+}
+
+export type DecisionRequest = Omit<Parameters<typeof recommendCandidate>[0], 'provider' | 'timeoutMs'> & {
+  /** Trusted host contract, not a model-selected mode. Defaults to entity selection. */
+  purpose?: JevDecisionPurpose
+}
+
+export interface DecisionClient {
+  readonly provider: 'typesafe'
+  readonly model: string
+  readonly timeoutMs: number
+  recommend(request: DecisionRequest): Promise<DecisionResult>
+}
+
+/** Validate once on construction. Errors never include supplied values or secrets. */
+export function createConfiguredDecisionClient(config: AIDecisionConfig | null | undefined): DecisionClient | undefined {
+  if (!config || config.enabled === false) return undefined
+  if (config.enabled !== true) throw new Error('aiDecision.enabled must be a boolean')
+  if (config.provider !== 'typesafe') throw new Error('aiDecision.provider is not supported')
+  const model = config.model ?? JEV_DECISION_MODEL
+  if (model !== JEV_DECISION_MODEL) throw new Error('aiDecision.model must use the supported pinned version')
+  const timeoutMs = config.timeoutMs ?? 300
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 1 || timeoutMs > 10000) throw new Error('aiDecision.timeoutMs must be between 1 and 10000')
+  if (typeof config.apiKey !== 'string' || !config.apiKey.trim()) throw new Error('aiDecision.apiKey is required when enabled')
+  const provider = createJevDecisionProvider(config.apiKey.trim())
+  const actionProvider = createJevDecisionProvider(config.apiKey.trim(), fetch, 'action')
+  return Object.freeze({
+    provider: 'typesafe' as const, model, timeoutMs,
+    recommend: async ({ purpose = 'entity', ...request }: DecisionRequest) => {
+      if (purpose !== 'entity' && purpose !== 'action') throw new Error('Unsupported decision purpose')
+      return recommendCandidate({ ...request, provider: purpose === 'action' ? actionProvider : provider, timeoutMs })
+    }
+  })
+}
+
+/** Server configuration only; constructing this client performs no network request and does not cache credentials. */
+export function getDefaultDecisionClient(): DecisionClient | undefined {
+  return createConfiguredDecisionClient(envConfig.get('aiDecision', null) as AIDecisionConfig | null)
+}

package/server/service/decision/decision.test.ts

@@ -0,0 +1,94 @@
+import { recommendCandidate, type DecisionProvider } from './decision'
+import { createJevDecisionProvider } from './jev'
+
+const candidates = [
+  { key: 'a', label: '주문 100', description: '서울 출고' },
+  { key: 'b', label: '주문 200', description: '부산 출고' }
+]
+const answer = { choice: 'a', confidence: 0.92, probabilities: { a: 0.94, b: 0.03, __none__: 0.03 } }
+const input = () => ({ query: '주문 100', candidates, mayRead: async () => true, isCurrent: () => true })
+const provider = (reply: unknown): DecisionProvider => ({ name: 'fixture', choose: async () => reply })
+
+test('baseline selects exact references, abstains on ambiguity and semantic questions', async () => {
+  expect((await recommendCandidate(input())).candidateKey).toBe('a')
+  expect((await recommendCandidate({ ...input(), query: '서울로 가는 것' })).reason).toBe('no-match')
+  expect((await recommendCandidate({ ...input(), candidates: candidates.map(c => ({ ...c, label: '주문 100' })) })).reason).toBe('no-match')
+})
+
+test('permission filtering happens before model exposure, and failure closes access', async () => {
+  const choose = jest.fn(async (_q, list) => {
+    expect(list.map((c: any) => c.key)).toEqual(['a'])
+    return { choice: 'a', confidence: 1, probabilities: { a: 1, __none__: 0 } }
+  })
+  const result = await recommendCandidate({ ...input(), provider: { name: 'spy', choose }, mayRead: async c => {
+    if (c.key === 'b') throw new Error('permission service unavailable')
+    return true
+  } })
+  expect(result.candidateKey).toBe('a')
+  expect(result.eligible).toBe(1)
+})
+
+test.each([
+  { ...answer, choice: 'invented' },
+  { ...answer, confidence: NaN },
+  { ...answer, probabilities: { a: 1 } },
+  { ...answer, probabilities: { a: 0.4, b: 0.5, __none__: 0.1 } },
+  { ...answer, probabilities: { a: 0.94, b: 0.3, __none__: 0.3 } }
+])('invalid model reply cannot become a target', async reply => {
+  expect((await recommendCandidate({ ...input(), provider: provider(reply) })).reason).toBe('invalid-reply')
+})
+
+test('uncertain, revoked and stale answers do not recommend a target', async () => {
+  expect((await recommendCandidate({ ...input(), provider: provider({ ...answer, confidence: 0.6 }) })).reason).toBe('uncertain')
+  let reads = 0
+  expect((await recommendCandidate({ ...input(), provider: provider(answer), mayRead: async () => ++reads <= 2 })).reason).toBe('access-changed')
+  let current = true
+  expect((await recommendCandidate({ ...input(), isCurrent: () => current, provider: { name: 'late', choose: async () => {
+    current = false
+    return answer
+  } } })).reason).toBe('stale-context')
+})
+
+test('deadline covers hanging permissions and aborts hanging model requests', async () => {
+  expect((await recommendCandidate({ ...input(), timeoutMs: 10, mayRead: () => new Promise(() => {}) })).reason).toBe('timeout')
+  let signal: AbortSignal | undefined
+  const result = await recommendCandidate({ ...input(), timeoutMs: 10, provider: { name: 'hanging', choose: async (_q, _c, s) => {
+    signal = s
+    return new Promise(() => {})
+  } } })
+  expect(result.reason).toBe('timeout')
+  expect(signal?.aborted).toBe(true)
+})
+
+test('duplicate or oversized shortlist is rejected before provider access', async () => {
+  const choose = jest.fn()
+  expect((await recommendCandidate({ ...input(), candidates: [candidates[0], candidates[0]], provider: { name: 'spy', choose } })).reason).toBe('invalid-input')
+  expect((await recommendCandidate({ ...input(), candidates: Array.from({ length: 13 }, (_, i) => ({ ...candidates[0], key: String(i) })), provider: { name: 'spy', choose } })).reason).toBe('invalid-input')
+  expect(choose).not.toHaveBeenCalled()
+})
+
+test('Jev uses a pinned typed request and propagates cancellation without returning secrets', async () => {
+  const transport = jest.fn(async () => ({ ok: true, json: async () => ({ model: 'jev-1.13.0', answers: { entity: { type: 'choice', ...answer } } }) }))
+  const result = await recommendCandidate({ ...input(), provider: createJevDecisionProvider('synthetic-key', transport as any) })
+  expect(result.candidateKey).toBe('a')
+  const [url, options] = (transport.mock.calls as any)[0]
+  expect(url).toBe('https://api.typesafe.ai/v1/systemone')
+  const request = JSON.parse(options.body)
+  expect(request.model).toBe('jev-1.13.0')
+  expect(request.questions.entity.criteria.__none__).toBeTruthy()
+  expect(options.signal).toBeInstanceOf(AbortSignal)
+  expect(JSON.stringify(result)).not.toContain('synthetic-key')
+})
+
+test('action classification uses an explicit contract and never accepts an entity answer', async () => {
+  const transport = jest.fn(async () => ({ ok: true, json: async () => ({ model: 'jev-1.13.0', answers: { action: { type: 'choice', ...answer } } }) }))
+  const result = await recommendCandidate({ ...input(), provider: createJevDecisionProvider('synthetic-key', transport as any, 'action') })
+  expect(result.candidateKey).toBe('a')
+  const request = JSON.parse((transport.mock.calls as any)[0][1].body)
+  expect(Object.keys(request.questions)).toEqual(['action'])
+  expect(request.questions.action.instructions).toContain('never execute')
+  expect(request.questions.action.instructions).toContain('multiple workflows')
+  const wrongPurpose = async () => ({ ok: true, json: async () => ({ model: 'jev-1.13.0', answers: { entity: { type: 'choice', ...answer } } }) })
+  expect((await recommendCandidate({ ...input(), provider: createJevDecisionProvider('synthetic-key', wrongPurpose as any, 'action') })).reason).toBe('provider-error')
+  expect(() => createJevDecisionProvider('synthetic-key', transport as any, 'unknown' as any)).toThrow('Unsupported decision purpose')
+})