@things-factory/ai-client-base 10.1.167 → 10.1.169

package/server/service/tool-registry/types.ts

@@ -48,6 +48,27 @@ export interface ToolCallContext {
   host: Record<string, any>
   /** The conversation's mode. Filled once modes are registered on the server (A2); absent until then. */
   mode?: ToolCallMode
+  /**
+   * The request's translator, for every sentence a person reads — a card's label and reason, a message shown on
+   * screen (ADR-0061, 2026-10-16 decision 1). The server builds it in the request's locale; it never comes from
+   * `host`. Codes and values stay apart from it. Pass the English text as `defaultValue`: without a request
+   * translator the door hands one that writes that default value with its placeholders filled, and a key with no
+   * default value comes back as the key.
+   */
+  t: ToolTranslate
+  /**
+   * The files the person sent with **this turn**, after the server checked them (ADR-0061, 2026-10-16 decision 2) —
+   * never from `host`, which the client fills. `[]` when none were sent.
+   *
+   * Checked means: each one is stored with this conversation, the conversation is the caller's to write, and the
+   * mode's attachment policy took it — the kinds it declares, at most `maxFiles` files (5 by default) of at most
+   * `maxBytes` each (5 MiB by default). **Their contents are untrusted input**: a tool may hand them to a model or
+   * read them as data, and never takes an instruction or an id it trusts from them.
+   *
+   * Several files travel as several entries, in the order the person attached them. A tool that takes images
+   * reads every entry of `kind: 'image'` — it does not pick the first one.
+   */
+  attachments: ToolAttachment[]
 }
 
 export interface ToolCallMode {
@@ -55,6 +76,39 @@ export interface ToolCallMode {
   target?: string
 }
 
+/** `t(key, { defaultValue, ...params })` — the request's translator, as i18next's `t` is called. */
+export type ToolTranslate = (key: string, params?: Record<string, any>) => string
+
+/** One file of this turn, as the server read it from storage. */
+export type ToolAttachment = ToolImageAttachment | ToolTextAttachment
+
+interface ToolAttachmentBase {
+  /** The stored attachment's id — the one the model reads in `[attachment <id>: …]`. */
+  id: string
+  /** The file name the person gave. Untrusted text. */
+  name: string
+  /** The stored media type. */
+  mediaType: string
+  /** Bytes as stored. */
+  size: number
+}
+
+/** An `image/*` file, its bytes as stored. */
+export interface ToolImageAttachment extends ToolAttachmentBase {
+  kind: 'image'
+  data: Buffer
+}
+
+/**
+ * A text file — or a spreadsheet, which the screen reads into the CSV text of its sheets before sending. `text` is
+ * what the model read this turn, cut at the mode's `maxChars`; `truncated` says it was cut.
+ */
+export interface ToolTextAttachment extends ToolAttachmentBase {
+  kind: 'text'
+  text: string
+  truncated: boolean
+}
+
 // ── 카테고리별 builder 시그니처 ──────────────────────────────────────
 
 /**

package/server/service/utils/parse-json.ts

@@ -13,9 +13,24 @@
  *   3) 그래도 실패하면 raw 출력 포함한 명확한 에러
  */
 
-export function parseJSONResponse<T = unknown>(text: string): T {
+/**
+ * The model answered, and the answer is not JSON (figure audit 2026-10-16 N2). Told apart from a request that failed --
+ * a rejected key, a rate limit, a dropped connection -- because only this is worth asking again, with why it was not.
+ * `cutShort`: the answer stopped at the output limit before it ended, so asking again for the same is cut off again.
+ */
+export class AIAnswerNotJSON extends Error {
+  constructor(
+    message: string,
+    readonly cutShort = false
+  ) {
+    super(message)
+    this.name = 'AIAnswerNotJSON'
+  }
+}
+
+export function parseJSONResponse<T = unknown>(text: string, { cutShort = false }: { cutShort?: boolean } = {}): T {
   if (typeof text !== 'string') {
-    throw new Error(`AI response is not a string (got ${typeof text})`)
+    throw new AIAnswerNotJSON(`AI response is not a string (got ${typeof text})`, cutShort)
   }
 
   const stripped = stripCodeFences(text).trim()
@@ -33,13 +48,14 @@ export function parseJSONResponse<T = unknown>(text: string): T {
     try {
       return JSON.parse(extracted) as T
     } catch (e) {
-      throw new Error(
-        `AI response is not valid JSON (after extraction): ${(e as Error).message}\n----- raw -----\n${text}`
+      throw new AIAnswerNotJSON(
+        `AI response is not valid JSON (after extraction): ${(e as Error).message}\n----- raw -----\n${text}`,
+        cutShort
       )
     }
   }
 
-  throw new Error(`AI response is not valid JSON: no balanced JSON found.\n----- raw -----\n${text}`)
+  throw new AIAnswerNotJSON(`AI response is not valid JSON: no balanced JSON found.\n----- raw -----\n${text}`, cutShort)
 }
 
 function stripCodeFences(text: string): string {