@things-factory/ai-client-base 10.1.3 → 10.1.7

package/dist-server/service/assistant/abort-notice.d.ts

@@ -0,0 +1,7 @@
+import type { AgenticLoopResult } from '../agentic-loop/index.js';
+/**
+ * 중단 이유 → 답에 덧붙일 한 줄. 정상 종료면 빈 문자열이다.
+ *
+ * 답을 고치지 않고 **뒤에 붙인다** — 모델이 한 말을 우리가 다시 쓰지 않는다.
+ */
+export declare function formatAbortNotice(abortReason: AgenticLoopResult<any>['abortReason']): string;

package/dist-server/service/assistant/abort-notice.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAbortNotice = formatAbortNotice;
+const index_js_1 = require("../utils/index.js");
+/**
+ * 중단 이유 → 답에 덧붙일 한 줄. 정상 종료면 빈 문자열이다.
+ *
+ * 답을 고치지 않고 **뒤에 붙인다** — 모델이 한 말을 우리가 다시 쓰지 않는다.
+ */
+function formatAbortNotice(abortReason) {
+    if (!abortReason)
+        return '';
+    switch (abortReason.type) {
+        case 'aborted':
+            return '\n\n_(요청이 중단되어 일부만 처리됐어요.)_';
+        case 'provider_error':
+            /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다 — "Error fetching from undefined: [503 …]" 은
+             * 사용자가 할 수 있는 일을 알려주지 않는다. 일시 장애는 이미 몇 번 다시 시도한 뒤이므로,
+             * 지금 필요한 안내는 "잠시 후 다시" 하나다. 원문은 서버 로그에 남는다. */
+            return (0, index_js_1.isTransientAIError)({ message: abortReason.message })
+                ? '\n\n_(AI 서비스가 일시적으로 응답하지 않았어요. 잠시 후 다시 시도해 주세요.)_'
+                : '\n\n_(처리 중 오류가 발생했어요. 같은 요청이 계속 실패하면 관리자에게 알려 주세요.)_';
+        case 'max_iterations':
+            return `\n\n_(작업이 너무 길어 ${abortReason.iter}회에서 중단했어요. 더 작게 나눠 요청해보세요.)_`;
+        case 'repeated_validation_failure':
+            return `\n\n_(\`${abortReason.toolName}\` 호출이 ${abortReason.consecutive}회 연속 실패해 중단했어요. 요청을 다시 표현해보세요.)_`;
+    }
+}
+//# sourceMappingURL=abort-notice.js.map

package/dist-server/service/assistant/abort-notice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-notice.js","sourceRoot":"","sources":["../../../server/service/assistant/abort-notice.ts"],"names":[],"mappings":";;AA0BA,8CAiBC;AAxBD,gDAAsD;AAEtD;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,WAAkD;IAClF,IAAI,CAAC,WAAW;QAAE,OAAO,EAAE,CAAA;IAC3B,QAAQ,WAAW,CAAC,IAAI,EAAE,CAAC;QACzB,KAAK,SAAS;YACZ,OAAO,6BAA6B,CAAA;QACtC,KAAK,gBAAgB;YACnB;;2DAE+C;YAC/C,OAAO,IAAA,6BAAkB,EAAC,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC;gBACzD,CAAC,CAAC,mDAAmD;gBACrD,CAAC,CAAC,sDAAsD,CAAA;QAC5D,KAAK,gBAAgB;YACnB,OAAO,mBAAmB,WAAW,CAAC,IAAI,8BAA8B,CAAA;QAC1E,KAAK,6BAA6B;YAChC,OAAO,WAAW,WAAW,CAAC,QAAQ,UAAU,WAAW,CAAC,WAAW,kCAAkC,CAAA;IAC7G,CAAC;AACH,CAAC","sourcesContent":["/*\n * Why the loop stopped, said to the person who asked.\n *\n * ── Why this is here and not in a product (2026-09-10) ───────────────────────────\n * This came out of `board-ai`. It is not board's: every product that runs the agentic loop can\n * have it stop early, and a reply that was cut off looks exactly like a reply that finished.\n *\n * The loop already reports why it stopped — `AgenticLoopResult.abortReason`. Nothing forces the\n * caller to say so. A product that forgets prints a truncated answer as though it were complete,\n * and the person acts on half of it. That failure is silent by construction, which is why the\n * notice belongs beside the loop rather than beside each product's prose.\n *\n * ── Known debt: the strings are Korean ─────────────────────────────────────────\n * They were Korean in board-ai and they still are. Moving them does not make that worse, but a\n * framework package is the wrong home for untranslated user-facing text. When this needs a second\n * locale, the shape is a caller-supplied translator, not a table in here — the notice is one line\n * appended to a reply the product already owns.\n */\nimport type { AgenticLoopResult } from '../agentic-loop/index.js'\nimport { isTransientAIError } from '../utils/index.js'\n\n/**\n * 중단 이유 → 답에 덧붙일 한 줄. 정상 종료면 빈 문자열이다.\n *\n * 답을 고치지 않고 **뒤에 붙인다** — 모델이 한 말을 우리가 다시 쓰지 않는다.\n */\nexport function formatAbortNotice(abortReason: AgenticLoopResult<any>['abortReason']): string {\n  if (!abortReason) return ''\n  switch (abortReason.type) {\n    case 'aborted':\n      return '\\n\\n_(요청이 중단되어 일부만 처리됐어요.)_'\n    case 'provider_error':\n      /* 남의 말(SDK 원문)을 사용자에게 보여주지 않는다 — \"Error fetching from undefined: [503 …]\" 은\n       * 사용자가 할 수 있는 일을 알려주지 않는다. 일시 장애는 이미 몇 번 다시 시도한 뒤이므로,\n       * 지금 필요한 안내는 \"잠시 후 다시\" 하나다. 원문은 서버 로그에 남는다. */\n      return isTransientAIError({ message: abortReason.message })\n        ? '\\n\\n_(AI 서비스가 일시적으로 응답하지 않았어요. 잠시 후 다시 시도해 주세요.)_'\n        : '\\n\\n_(처리 중 오류가 발생했어요. 같은 요청이 계속 실패하면 관리자에게 알려 주세요.)_'\n    case 'max_iterations':\n      return `\\n\\n_(작업이 너무 길어 ${abortReason.iter}회에서 중단했어요. 더 작게 나눠 요청해보세요.)_`\n    case 'repeated_validation_failure':\n      return `\\n\\n_(\\`${abortReason.toolName}\\` 호출이 ${abortReason.consecutive}회 연속 실패해 중단했어요. 요청을 다시 표현해보세요.)_`\n  }\n}\n"]}

package/dist-server/service/assistant/assistant-chat.d.ts

@@ -0,0 +1,41 @@
+import { type AgenticLoopInput, type AgenticLoopResult } from '../agentic-loop/index.js';
+import { type GroundingSources } from '../utils/index.js';
+export interface AssistantChatInput<TCtx = unknown, TOp = unknown> extends AgenticLoopInput<TCtx, TOp> {
+    /**
+     * 이 턴에 모델이 본 것 — **도구 결과 말고** 전부. 도구 결과는 이 함수가 루프에서 받아 더한다.
+     *
+     * 빠뜨리면 정상 답이 경고를 받는다(오탐). 시스템 프롬프트에 적어 보낸 타입 이름을 모델이 말하는
+     * 것은 근거 있는 발언이다.
+     */
+    groundingSources?: Omit<GroundingSources, 'toolResults'>;
+    /**
+     * 접지 검사를 끈다 — **기본은 켜짐.**
+     *
+     * 끄는 것이 맞는 자리가 있다: 식별자를 다루지 않는 대화(문서 상담·개념 질문)는 근거집합에 식별자가
+     * 없어 모든 고유명사가 경고로 나온다. 그때는 끄는 것이 정직하고, **켠 채로 경고를 버리는 것**이
+     * 정직하지 않다.
+     */
+    skipGrounding?: boolean;
+}
+export interface AssistantChatResult<TOp = unknown> {
+    /**
+     * 사용자에게 보일 답 — 모델의 마지막 말 + 중단 통지.
+     *
+     * 모델의 말을 고치지 않는다. 통지는 **뒤에 붙는다.**
+     */
+    reply: string;
+    /** 통지가 붙기 전의 답. 접지 검사가 본 것이고, 호스트가 다시 판정할 때 쓴다. */
+    baseText: string;
+    /** 근거 밖의 식별자를 지목한 자리들. 없으면 undefined — 빈 배열을 주지 않는다. */
+    groundingWarnings?: string[];
+    /** 루프 결과 원본 — 쓰기 호출·조치·제안·도구 흔적. 호스트가 자기 뜻으로 해석한다. */
+    loop: AgenticLoopResult<TOp>;
+}
+/**
+ * 한 턴을 돌린다.
+ *
+ * `lastText` 가 없을 수 있다(도구만 부르고 말을 안 한 턴). 그 경우 `baseText` 는 빈 문자열이고,
+ * 무엇을 대신 말할지는 호스트가 정한다 — 여기서 「변경했습니다」 같은 말을 지어내지 않는다.
+ * 도메인을 모르는 자리에서 결과를 서술하면 그것이 곧 지어낸 원인이 된다.
+ */
+export declare function assistantChat<TCtx = unknown, TOp = unknown>(input: AssistantChatInput<TCtx, TOp>): Promise<AssistantChatResult<TOp>>;

package/dist-server/service/assistant/assistant-chat.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assistantChat = assistantChat;
+/*
+ * One turn of an assistant — the loop **with the guards that must not be optional.**
+ *
+ * ── Why this exists (2026-09-10) ────────────────────────────────────────────────
+ * `runAgenticLoop` is neutral and has been since 2026-09-05, when the same loop running in two
+ * places was consolidated. The note on that change is the reason this file exists: it was "not a
+ * duplication, a defect" — the two copies had **their safety measures set opposite ways**.
+ *
+ * The loop came out. The guards around it did not. They stayed in `board-ai`, wrapped around
+ * `DefaultBoardAIAssistant.chat`, which meant a product with no board of its own could only get
+ * them by going through the board editor. The plant lane read that correctly — it uses none of
+ * board's session machinery — and asked whether it could call `runAgenticLoop` directly instead.
+ *
+ * The answer was no, and the reason is written in `board-ai`'s own grounding file: the twin's
+ * header route had a grounding guard and its dock route did not, so **the same question was
+ * verified on one side and not the other.** A per-product door makes that three ways. This file is
+ * the door instead.
+ *
+ * ── What is guaranteed here, and what the host still owns ───────────────────────
+ * Guaranteed, because a caller cannot skip it:
+ *   · the loop stops for a reason and the reason reaches the reply  (`formatAbortNotice`)
+ *   · the reply is checked against what the model was actually given (`groundingWarnings`)
+ *
+ * Still the host's, because only the host knows the domain:
+ *   · which tools exist and what a write call means      → `gate`, `dispatch`
+ *   · what counts as evidence beyond the tool results    → `groundingSources`
+ *
+ * ── Grounding sources: leaving one out produces false warnings ──────────────────
+ * The corpus is everything the model saw this turn. The tool results are added here, from
+ * `groundedTexts` — the raw strings sent back as `tool_result`, never `toolUsages[].result`, which
+ * is depth-limited for display. A check reading the display copy can pass while the model was
+ * handed `{}`; an un-awaited async builder did exactly that.
+ *
+ * Anything else the host put in front of the model — a system prompt, a state summary, the user's
+ * own words — has to be declared, or a correct answer quoting it gets warned about.
+ */
+const index_js_1 = require("../agentic-loop/index.js");
+const index_js_2 = require("../utils/index.js");
+const abort_notice_js_1 = require("./abort-notice.js");
+/**
+ * 한 턴을 돌린다.
+ *
+ * `lastText` 가 없을 수 있다(도구만 부르고 말을 안 한 턴). 그 경우 `baseText` 는 빈 문자열이고,
+ * 무엇을 대신 말할지는 호스트가 정한다 — 여기서 「변경했습니다」 같은 말을 지어내지 않는다.
+ * 도메인을 모르는 자리에서 결과를 서술하면 그것이 곧 지어낸 원인이 된다.
+ */
+async function assistantChat(input) {
+    const { groundingSources, skipGrounding, ...loopInput } = input;
+    const loop = await (0, index_js_1.runAgenticLoop)(loopInput);
+    const baseText = loop.lastText ?? '';
+    const reply = baseText + (0, abort_notice_js_1.formatAbortNotice)(loop.abortReason);
+    let warnings;
+    if (!skipGrounding && baseText) {
+        const corpus = (0, index_js_2.buildGroundedCorpus)({ ...(groundingSources ?? {}), toolResults: loop.groundedTexts });
+        const found = (0, index_js_2.groundingWarnings)(baseText, corpus);
+        warnings = found.length > 0 ? found : undefined;
+    }
+    return { reply, baseText, groundingWarnings: warnings, loop };
+}
+//# sourceMappingURL=assistant-chat.js.map

package/dist-server/service/assistant/assistant-chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-chat.js","sourceRoot":"","sources":["../../../server/service/assistant/assistant-chat.ts"],"names":[],"mappings":";;AAgFA,sCAkBC;AAlGD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,uDAAwG;AACxG,gDAAiG;AACjG,uDAAqD;AAmCrD;;;;;;GAMG;AACI,KAAK,UAAU,aAAa,CACjC,KAAoC;IAEpC,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,GAAG,SAAS,EAAE,GAAG,KAAK,CAAA;IAE/D,MAAM,IAAI,GAAG,MAAM,IAAA,yBAAc,EAAY,SAAS,CAAC,CAAA;IAEvD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAA;IACpC,MAAM,KAAK,GAAG,QAAQ,GAAG,IAAA,mCAAiB,EAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IAE5D,IAAI,QAA8B,CAAA;IAClC,IAAI,CAAC,aAAa,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,IAAA,8BAAmB,EAAC,EAAE,GAAG,CAAC,gBAAgB,IAAI,EAAE,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAA;QACpG,MAAM,KAAK,GAAG,IAAA,4BAAiB,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAA;QACjD,QAAQ,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;IACjD,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,iBAAiB,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAA;AAC/D,CAAC","sourcesContent":["/*\n * One turn of an assistant — the loop **with the guards that must not be optional.**\n *\n * ── Why this exists (2026-09-10) ────────────────────────────────────────────────\n * `runAgenticLoop` is neutral and has been since 2026-09-05, when the same loop running in two\n * places was consolidated. The note on that change is the reason this file exists: it was \"not a\n * duplication, a defect\" — the two copies had **their safety measures set opposite ways**.\n *\n * The loop came out. The guards around it did not. They stayed in `board-ai`, wrapped around\n * `DefaultBoardAIAssistant.chat`, which meant a product with no board of its own could only get\n * them by going through the board editor. The plant lane read that correctly — it uses none of\n * board's session machinery — and asked whether it could call `runAgenticLoop` directly instead.\n *\n * The answer was no, and the reason is written in `board-ai`'s own grounding file: the twin's\n * header route had a grounding guard and its dock route did not, so **the same question was\n * verified on one side and not the other.** A per-product door makes that three ways. This file is\n * the door instead.\n *\n * ── What is guaranteed here, and what the host still owns ───────────────────────\n * Guaranteed, because a caller cannot skip it:\n *   · the loop stops for a reason and the reason reaches the reply  (`formatAbortNotice`)\n *   · the reply is checked against what the model was actually given (`groundingWarnings`)\n *\n * Still the host's, because only the host knows the domain:\n *   · which tools exist and what a write call means      → `gate`, `dispatch`\n *   · what counts as evidence beyond the tool results    → `groundingSources`\n *\n * ── Grounding sources: leaving one out produces false warnings ──────────────────\n * The corpus is everything the model saw this turn. The tool results are added here, from\n * `groundedTexts` — the raw strings sent back as `tool_result`, never `toolUsages[].result`, which\n * is depth-limited for display. A check reading the display copy can pass while the model was\n * handed `{}`; an un-awaited async builder did exactly that.\n *\n * Anything else the host put in front of the model — a system prompt, a state summary, the user's\n * own words — has to be declared, or a correct answer quoting it gets warned about.\n */\nimport { runAgenticLoop, type AgenticLoopInput, type AgenticLoopResult } from '../agentic-loop/index.js'\nimport { buildGroundedCorpus, groundingWarnings, type GroundingSources } from '../utils/index.js'\nimport { formatAbortNotice } from './abort-notice.js'\n\nexport interface AssistantChatInput<TCtx = unknown, TOp = unknown> extends AgenticLoopInput<TCtx, TOp> {\n  /**\n   * 이 턴에 모델이 본 것 — **도구 결과 말고** 전부. 도구 결과는 이 함수가 루프에서 받아 더한다.\n   *\n   * 빠뜨리면 정상 답이 경고를 받는다(오탐). 시스템 프롬프트에 적어 보낸 타입 이름을 모델이 말하는\n   * 것은 근거 있는 발언이다.\n   */\n  groundingSources?: Omit<GroundingSources, 'toolResults'>\n  /**\n   * 접지 검사를 끈다 — **기본은 켜짐.**\n   *\n   * 끄는 것이 맞는 자리가 있다: 식별자를 다루지 않는 대화(문서 상담·개념 질문)는 근거집합에 식별자가\n   * 없어 모든 고유명사가 경고로 나온다. 그때는 끄는 것이 정직하고, **켠 채로 경고를 버리는 것**이\n   * 정직하지 않다.\n   */\n  skipGrounding?: boolean\n}\n\nexport interface AssistantChatResult<TOp = unknown> {\n  /**\n   * 사용자에게 보일 답 — 모델의 마지막 말 + 중단 통지.\n   *\n   * 모델의 말을 고치지 않는다. 통지는 **뒤에 붙는다.**\n   */\n  reply: string\n  /** 통지가 붙기 전의 답. 접지 검사가 본 것이고, 호스트가 다시 판정할 때 쓴다. */\n  baseText: string\n  /** 근거 밖의 식별자를 지목한 자리들. 없으면 undefined — 빈 배열을 주지 않는다. */\n  groundingWarnings?: string[]\n  /** 루프 결과 원본 — 쓰기 호출·조치·제안·도구 흔적. 호스트가 자기 뜻으로 해석한다. */\n  loop: AgenticLoopResult<TOp>\n}\n\n/**\n * 한 턴을 돌린다.\n *\n * `lastText` 가 없을 수 있다(도구만 부르고 말을 안 한 턴). 그 경우 `baseText` 는 빈 문자열이고,\n * 무엇을 대신 말할지는 호스트가 정한다 — 여기서 「변경했습니다」 같은 말을 지어내지 않는다.\n * 도메인을 모르는 자리에서 결과를 서술하면 그것이 곧 지어낸 원인이 된다.\n */\nexport async function assistantChat<TCtx = unknown, TOp = unknown>(\n  input: AssistantChatInput<TCtx, TOp>\n): Promise<AssistantChatResult<TOp>> {\n  const { groundingSources, skipGrounding, ...loopInput } = input\n\n  const loop = await runAgenticLoop<TCtx, TOp>(loopInput)\n\n  const baseText = loop.lastText ?? ''\n  const reply = baseText + formatAbortNotice(loop.abortReason)\n\n  let warnings: string[] | undefined\n  if (!skipGrounding && baseText) {\n    const corpus = buildGroundedCorpus({ ...(groundingSources ?? {}), toolResults: loop.groundedTexts })\n    const found = groundingWarnings(baseText, corpus)\n    warnings = found.length > 0 ? found : undefined\n  }\n\n  return { reply, baseText, groundingWarnings: warnings, loop }\n}\n"]}

package/dist-server/service/assistant/index.d.ts

@@ -0,0 +1,5 @@
+export * from './abort-notice.js';
+export * from './summarize.js';
+export * from './registry-gate.js';
+export * from './assistant-chat.js';
+export * from './registry-assistant.js';

package/dist-server/service/assistant/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/*
+ * The neutral assistant layer — the agentic loop plus the guards that must not be optional.
+ *
+ * See `assistant-chat.ts` for why this is not in a product package.
+ */
+tslib_1.__exportStar(require("./abort-notice.js"), exports);
+tslib_1.__exportStar(require("./summarize.js"), exports);
+tslib_1.__exportStar(require("./registry-gate.js"), exports);
+tslib_1.__exportStar(require("./assistant-chat.js"), exports);
+tslib_1.__exportStar(require("./registry-assistant.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist-server/service/assistant/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../server/service/assistant/index.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,4DAAiC;AACjC,yDAA8B;AAC9B,6DAAkC;AAClC,8DAAmC;AACnC,kEAAuC","sourcesContent":["/*\n * The neutral assistant layer — the agentic loop plus the guards that must not be optional.\n *\n * See `assistant-chat.ts` for why this is not in a product package.\n */\nexport * from './abort-notice.js'\nexport * from './summarize.js'\nexport * from './registry-gate.js'\nexport * from './assistant-chat.js'\nexport * from './registry-assistant.js'\n"]}

package/dist-server/service/assistant/registry-assistant.d.ts

@@ -0,0 +1,46 @@
+import type { AIClient, AIMessage } from '../types.js';
+import { type AssistantChatResult } from './assistant-chat.js';
+import type { GroundingSources } from '../utils/index.js';
+/** What a registry tool is handed when it runs. `state` is the caller's koa state. */
+export interface RegistryToolCallContext {
+    state: any;
+    /** What this surface is looking at — the host passes it through; tools read it as `host`. */
+    host?: any;
+}
+export interface RegistryAssistantInput {
+    /** Provider client. Must implement `chatWithTools`. */
+    client: AIClient;
+    /** The conversation so far, newest last. The caller owns history and truncation. */
+    messages: AIMessage[];
+    /** Who the assistant is and what this surface is. The host owns this prose. */
+    systemPrompt: string;
+    /**
+     * Categories this conversation may use. Omit to allow every registered category.
+     *
+     * An empty array is not the same as omitting: it allows nothing, and the conversation runs with
+     * no tools at all. That is a legitimate surface (plain chat), so it is not corrected here.
+     */
+    toolCategories?: string[];
+    /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */
+    hostContext?: any;
+    /** Caller's koa state (domain, user, tx). Tools that read the database need it. */
+    state: any;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Make the model call a tool before it may answer. For surfaces that report live state. */
+    requireToolOnFirstTurn?: boolean;
+    /** Texts the answer is allowed to draw identifiers from, besides the tool results. */
+    groundingSources?: Omit<GroundingSources, 'toolResults'>;
+}
+export interface RegistryAssistantResult extends AssistantChatResult<unknown> {
+    /** Tool names actually offered to the model this turn. The caller may log or return it. */
+    offeredTools: string[];
+}
+/**
+ * Run one turn of a conversation whose only tools come from the registry.
+ *
+ * Throws when the client cannot use tools at all — a surface built on registered tools that
+ * silently ran without them would answer from nothing and look like it had checked.
+ */
+export declare function registryAssistantChat(input: RegistryAssistantInput): Promise<RegistryAssistantResult>;

package/dist-server/service/assistant/registry-assistant.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registryAssistantChat = registryAssistantChat;
+const index_js_1 = require("../tool-registry/index.js");
+const assistant_chat_js_1 = require("./assistant-chat.js");
+const summarize_js_1 = require("./summarize.js");
+/** `read` and `external` are the two kinds that answer a question without changing a document. */
+function answeringSpecs(filter) {
+    return (0, index_js_1.getToolSpecsFor)(filter).filter(spec => spec.kind === 'read' || spec.kind === 'external');
+}
+/**
+ * Run one turn of a conversation whose only tools come from the registry.
+ *
+ * Throws when the client cannot use tools at all — a surface built on registered tools that
+ * silently ran without them would answer from nothing and look like it had checked.
+ */
+async function registryAssistantChat(input) {
+    const { client, messages, systemPrompt, toolCategories, hostContext, state } = input;
+    if (!client.chatWithTools) {
+        throw new Error('[registry-assistant] the configured AI client cannot call tools, so this conversation cannot run');
+    }
+    const filter = toolCategories;
+    const specs = answeringSpecs(filter);
+    const byName = new Map(specs.map(spec => [spec.name, spec]));
+    const tools = specs.map(spec => ({
+        name: spec.name,
+        description: spec.themeNote ? `${spec.description} ${spec.themeNote}` : spec.description,
+        parameters: spec.schema
+    }));
+    /*
+     * The rules for using a tool belong to whoever registered it. Collect only the exposed ones, so
+     * a surface never reads instructions for a category it cannot call.
+     */
+    const guidance = (0, index_js_1.getCategoryGuidance)(filter);
+    const prompt = guidance.length > 0 ? `${systemPrompt}\n\n${guidance.join('\n\n')}` : systemPrompt;
+    const toolContext = { state, host: hostContext };
+    const result = await (0, assistant_chat_js_1.assistantChat)({
+        initialConversation: messages,
+        tools,
+        options: {
+            systemPrompt: prompt,
+            model: input.model,
+            temperature: input.temperature,
+            maxTokens: input.maxTokens,
+            requireToolOnFirstTurn: input.requireToolOnFirstTurn
+        },
+        chat: (msgs, toolDefs, opts) => client.chatWithTools(msgs, toolDefs, opts),
+        context: toolContext,
+        dispatch: {
+            isReadTool: name => byName.has(name),
+            /*
+             * This surface has no document, so nothing here can write. Saying so plainly makes the loop
+             * report an unknown name back to the model instead of accepting a call and dropping it.
+             */
+            isWriteTool: () => false,
+            isActionTool: () => false,
+            executeReadTool: (call, context) => {
+                const spec = byName.get(call.name);
+                if (!spec)
+                    return undefined;
+                return spec.builder(call.arguments ?? {}, context);
+            },
+            validateWriteToolCall: () => ({ valid: false, errors: ['this conversation has no document to write to'] }),
+            toolCallToOp: () => null,
+            summarizeToolResult: summarize_js_1.summarizeToolResult
+        },
+        groundingSources: input.groundingSources
+    });
+    return { ...result, offeredTools: tools.map(tool => tool.name) };
+}
+//# sourceMappingURL=registry-assistant.js.map

package/dist-server/service/assistant/registry-assistant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-assistant.js","sourceRoot":"","sources":["../../../server/service/assistant/registry-assistant.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * A conversation for a product that has no editor of its own.\n *\n * ── What this is for ───────────────────────────────────────────────────────────\n * `board-ai` assembles its conversation from two sources: its own board editing tools, and\n * whatever other packages registered in the tool registry. The second half is the same work for\n * every product — read the specs, build the definitions, dispatch by name — but it only existed\n * inside the board assistant, so a product without a board had nowhere to ask a question from.\n * operato-figure hit exactly that: the dock was mounted, the tools were registered, and the only\n * mutation that could run them lived in a package figure does not load.\n *\n * ── Read and external only ─────────────────────────────────────────────────────\n * A registry category may also carry `write` and `action` tools. Those produce edit ops for a\n * document the host owns, and a host with no document cannot apply them. Offering them here would\n * declare a door with no road behind it — the model would call one and the call would go nowhere.\n * So this runner offers, and dispatches, `read` and `external` only. A host that owns a document\n * keeps assembling its own conversation, as board-ai does.\n *\n * The gate answers from the same list the definitions are built from, so what is offered and what\n * may be dispatched cannot drift apart.\n */\nimport type { AIClient, AIMessage } from '../types.js'\nimport { getCategoryGuidance, getToolSpecsFor, type ToolCategoryFilter, type ToolSpec } from '../tool-registry/index.js'\nimport { assistantChat, type AssistantChatResult } from './assistant-chat.js'\nimport { summarizeToolResult } from './summarize.js'\nimport type { GroundingSources } from '../utils/index.js'\n\n/** What a registry tool is handed when it runs. `state` is the caller's koa state. */\nexport interface RegistryToolCallContext {\n  state: any\n  /** What this surface is looking at — the host passes it through; tools read it as `host`. */\n  host?: any\n}\n\nexport interface RegistryAssistantInput {\n  /** Provider client. Must implement `chatWithTools`. */\n  client: AIClient\n  /** The conversation so far, newest last. The caller owns history and truncation. */\n  messages: AIMessage[]\n  /** Who the assistant is and what this surface is. The host owns this prose. */\n  systemPrompt: string\n  /**\n   * Categories this conversation may use. Omit to allow every registered category.\n   *\n   * An empty array is not the same as omitting: it allows nothing, and the conversation runs with\n   * no tools at all. That is a legitimate surface (plain chat), so it is not corrected here.\n   */\n  toolCategories?: string[]\n  /** Passed to tools as `context.host`. Client-supplied — never used for authorization. */\n  hostContext?: any\n  /** Caller's koa state (domain, user, tx). Tools that read the database need it. */\n  state: any\n  model?: string\n  temperature?: number\n  maxTokens?: number\n  /** Make the model call a tool before it may answer. For surfaces that report live state. */\n  requireToolOnFirstTurn?: boolean\n  /** Texts the answer is allowed to draw identifiers from, besides the tool results. */\n  groundingSources?: Omit<GroundingSources, 'toolResults'>\n}\n\nexport interface RegistryAssistantResult extends AssistantChatResult<unknown> {\n  /** Tool names actually offered to the model this turn. The caller may log or return it. */\n  offeredTools: string[]\n}\n\n/** `read` and `external` are the two kinds that answer a question without changing a document. */\nfunction answeringSpecs(filter: ToolCategoryFilter): ToolSpec[] {\n  return getToolSpecsFor(filter).filter(spec => spec.kind === 'read' || spec.kind === 'external')\n}\n\n/**\n * Run one turn of a conversation whose only tools come from the registry.\n *\n * Throws when the client cannot use tools at all — a surface built on registered tools that\n * silently ran without them would answer from nothing and look like it had checked.\n */\nexport async function registryAssistantChat(input: RegistryAssistantInput): Promise<RegistryAssistantResult> {\n  const { client, messages, systemPrompt, toolCategories, hostContext, state } = input\n\n  if (!client.chatWithTools) {\n    throw new Error('[registry-assistant] the configured AI client cannot call tools, so this conversation cannot run')\n  }\n\n  const filter: ToolCategoryFilter = toolCategories\n  const specs = answeringSpecs(filter)\n  const byName = new Map(specs.map(spec => [spec.name, spec]))\n\n  const tools = specs.map(spec => ({\n    name: spec.name,\n    description: spec.themeNote ? `${spec.description} ${spec.themeNote}` : spec.description,\n    parameters: spec.schema\n  }))\n\n  /*\n   * The rules for using a tool belong to whoever registered it. Collect only the exposed ones, so\n   * a surface never reads instructions for a category it cannot call.\n   */\n  const guidance = getCategoryGuidance(filter)\n  const prompt = guidance.length > 0 ? `${systemPrompt}\\n\\n${guidance.join('\\n\\n')}` : systemPrompt\n\n  const toolContext: RegistryToolCallContext = { state, host: hostContext }\n\n  const result = await assistantChat<RegistryToolCallContext, unknown>({\n    initialConversation: messages,\n    tools,\n    options: {\n      systemPrompt: prompt,\n      model: input.model,\n      temperature: input.temperature,\n      maxTokens: input.maxTokens,\n      requireToolOnFirstTurn: input.requireToolOnFirstTurn\n    },\n    chat: (msgs, toolDefs, opts) => client.chatWithTools!(msgs, toolDefs, opts),\n    context: toolContext,\n    dispatch: {\n      isReadTool: name => byName.has(name),\n      /*\n       * This surface has no document, so nothing here can write. Saying so plainly makes the loop\n       * report an unknown name back to the model instead of accepting a call and dropping it.\n       */\n      isWriteTool: () => false,\n      isActionTool: () => false,\n      executeReadTool: (call, context) => {\n        const spec = byName.get(call.name)\n        if (!spec) return undefined\n        return (spec.builder as any)(call.arguments ?? {}, context)\n      },\n      validateWriteToolCall: () => ({ valid: false, errors: ['this conversation has no document to write to'] }),\n      toolCallToOp: () => null,\n      summarizeToolResult\n    },\n    groundingSources: input.groundingSources\n  })\n\n  return { ...result, offeredTools: tools.map(tool => tool.name) }\n}\n"]}

package/dist-server/service/assistant/registry-gate.d.ts

@@ -0,0 +1,31 @@
+import { type ToolCategoryFilter, type ToolSpec } from '../tool-registry/index.js';
+/** 이름 하나에 대한 판정. 정의 조립과 dispatch 가 **같은 것**을 쓴다. */
+export interface ToolGate {
+    /** 이 대화에 허용된 카테고리 목록. 없음 = 전부. */
+    filter: ToolCategoryFilter;
+    isRead(name: string): boolean;
+    isWrite(name: string): boolean;
+    isAction(name: string): boolean;
+    spec(name: string): ToolSpec | undefined;
+}
+/** 호스트가 자기 도구를 더할 때 주는 것. 준 것만 더해지고, 안 준 축은 레지스트리 판정 그대로다. */
+export interface ToolGateExtension {
+    isRead?(name: string): boolean;
+    isWrite?(name: string): boolean;
+    isAction?(name: string): boolean;
+    spec?(name: string): ToolSpec | undefined;
+}
+/**
+ * 레지스트리만 보고 답하는 게이트.
+ *
+ * `external` 은 읽기로 본다 — 등록한 쪽이 「밖에서 값을 가져온다」고 말한 것이고, 그것은 쓰지 않는다.
+ */
+export declare function registryToolGate(filter?: ToolCategoryFilter): ToolGate;
+/**
+ * 호스트의 판정을 **더한다.** 겹치면 어느 쪽이든 참이면 참이다 — 게이트는 「이 이름을 다룰 수 있나」를
+ * 묻고, 두 출처 중 하나가 안다고 하면 다룰 수 있다.
+ *
+ * 한쪽으로 덮지 않는 이유: 덮으면 호스트가 자기 이름집합에 없는 등록 도구를 **조용히 잠근다.** 그러면
+ * 대화면이 카테고리를 허용했는데 호출이 미등록으로 회신되고, 원인이 두 자리에 나뉘어 있어 못 찾는다.
+ */
+export declare function extendToolGate(base: ToolGate, extension: ToolGateExtension): ToolGate;

package/dist-server/service/assistant/registry-gate.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registryToolGate = registryToolGate;
+exports.extendToolGate = extendToolGate;
+/*
+ * Which tools this conversation may call — the registry half.
+ *
+ * ── Why a gate at all ───────────────────────────────────────────────────────────
+ * One product grows several conversation surfaces (a board authoring dock, an operations dock, a
+ * header assistant). Board edits can be reverted; an operations command reaches a real factory.
+ * If both sets hang in one conversation, the boundary is a label on the screen.
+ *
+ * **Hiding the definitions is not enough.** A model can guess a name, and an older conversation
+ * can be replayed with tool calls still in it. So the same gate has to decide *both* what is
+ * offered and what may be dispatched. A name that fails the gate is reported back to the model as
+ * unregistered — never a silent no-op, which the model would read as success.
+ *
+ * ── Why the registry half is here and the rest is not (2026-09-10) ──────────────
+ * This came out of `board-ai`, where the gate answered from two sources at once: the tool registry
+ * *and* board's own core tool-name sets. The first is neutral — any host asking "what kind of tool
+ * is this name, and may this conversation see it" wants the same answer. The second is board's.
+ *
+ * So the registry half lives here and a host **extends** it with whatever it owns
+ * (`extendToolGate`). Splitting it this way is what lets a product with no board of its own get
+ * the same dispatch discipline, instead of each product writing its own gate and diverging — which
+ * is what happened with the grounding guard: the twin's header route had it and the dock route did
+ * not, so the same question was verified on one side and not the other.
+ */
+const index_js_1 = require("../tool-registry/index.js");
+/**
+ * 레지스트리만 보고 답하는 게이트.
+ *
+ * `external` 은 읽기로 본다 — 등록한 쪽이 「밖에서 값을 가져온다」고 말한 것이고, 그것은 쓰지 않는다.
+ */
+function registryToolGate(filter) {
+    const kind = (name) => (0, index_js_1.getToolKind)(name, filter);
+    return {
+        filter,
+        isRead: name => kind(name) === 'read' || kind(name) === 'external',
+        isWrite: name => kind(name) === 'write',
+        isAction: name => kind(name) === 'action',
+        spec: name => (0, index_js_1.findToolSpec)(name, filter)
+    };
+}
+/**
+ * 호스트의 판정을 **더한다.** 겹치면 어느 쪽이든 참이면 참이다 — 게이트는 「이 이름을 다룰 수 있나」를
+ * 묻고, 두 출처 중 하나가 안다고 하면 다룰 수 있다.
+ *
+ * 한쪽으로 덮지 않는 이유: 덮으면 호스트가 자기 이름집합에 없는 등록 도구를 **조용히 잠근다.** 그러면
+ * 대화면이 카테고리를 허용했는데 호출이 미등록으로 회신되고, 원인이 두 자리에 나뉘어 있어 못 찾는다.
+ */
+function extendToolGate(base, extension) {
+    return {
+        filter: base.filter,
+        isRead: name => base.isRead(name) || !!extension.isRead?.(name),
+        isWrite: name => base.isWrite(name) || !!extension.isWrite?.(name),
+        isAction: name => base.isAction(name) || !!extension.isAction?.(name),
+        spec: name => base.spec(name) ?? extension.spec?.(name)
+    };
+}
+//# sourceMappingURL=registry-gate.js.map

package/dist-server/service/assistant/registry-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-gate.js","sourceRoot":"","sources":["../../../server/service/assistant/registry-gate.ts"],"names":[],"mappings":";;AAiDA,4CASC;AASD,wCAQC;AA3ED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wDAA6G;AAoB7G;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,MAA2B;IAC1D,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAA,sBAAW,EAAC,IAAI,EAAE,MAAM,CAAC,CAAA;IACxD,OAAO;QACL,MAAM;QACN,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,UAAU;QAClE,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,OAAO;QACvC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,QAAQ;QACzC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,IAAA,uBAAY,EAAC,IAAI,EAAE,MAAM,CAAC;KACzC,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,cAAc,CAAC,IAAc,EAAE,SAA4B;IACzE,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;QAC/D,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC;QAClE,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC;QACrE,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC;KACxD,CAAA;AACH,CAAC","sourcesContent":["/*\n * Which tools this conversation may call — the registry half.\n *\n * ── Why a gate at all ───────────────────────────────────────────────────────────\n * One product grows several conversation surfaces (a board authoring dock, an operations dock, a\n * header assistant). Board edits can be reverted; an operations command reaches a real factory.\n * If both sets hang in one conversation, the boundary is a label on the screen.\n *\n * **Hiding the definitions is not enough.** A model can guess a name, and an older conversation\n * can be replayed with tool calls still in it. So the same gate has to decide *both* what is\n * offered and what may be dispatched. A name that fails the gate is reported back to the model as\n * unregistered — never a silent no-op, which the model would read as success.\n *\n * ── Why the registry half is here and the rest is not (2026-09-10) ──────────────\n * This came out of `board-ai`, where the gate answered from two sources at once: the tool registry\n * *and* board's own core tool-name sets. The first is neutral — any host asking \"what kind of tool\n * is this name, and may this conversation see it\" wants the same answer. The second is board's.\n *\n * So the registry half lives here and a host **extends** it with whatever it owns\n * (`extendToolGate`). Splitting it this way is what lets a product with no board of its own get\n * the same dispatch discipline, instead of each product writing its own gate and diverging — which\n * is what happened with the grounding guard: the twin's header route had it and the dock route did\n * not, so the same question was verified on one side and not the other.\n */\nimport { findToolSpec, getToolKind, type ToolCategoryFilter, type ToolSpec } from '../tool-registry/index.js'\n\n/** 이름 하나에 대한 판정. 정의 조립과 dispatch 가 **같은 것**을 쓴다. */\nexport interface ToolGate {\n  /** 이 대화에 허용된 카테고리 목록. 없음 = 전부. */\n  filter: ToolCategoryFilter\n  isRead(name: string): boolean\n  isWrite(name: string): boolean\n  isAction(name: string): boolean\n  spec(name: string): ToolSpec | undefined\n}\n\n/** 호스트가 자기 도구를 더할 때 주는 것. 준 것만 더해지고, 안 준 축은 레지스트리 판정 그대로다. */\nexport interface ToolGateExtension {\n  isRead?(name: string): boolean\n  isWrite?(name: string): boolean\n  isAction?(name: string): boolean\n  spec?(name: string): ToolSpec | undefined\n}\n\n/**\n * 레지스트리만 보고 답하는 게이트.\n *\n * `external` 은 읽기로 본다 — 등록한 쪽이 「밖에서 값을 가져온다」고 말한 것이고, 그것은 쓰지 않는다.\n */\nexport function registryToolGate(filter?: ToolCategoryFilter): ToolGate {\n  const kind = (name: string) => getToolKind(name, filter)\n  return {\n    filter,\n    isRead: name => kind(name) === 'read' || kind(name) === 'external',\n    isWrite: name => kind(name) === 'write',\n    isAction: name => kind(name) === 'action',\n    spec: name => findToolSpec(name, filter)\n  }\n}\n\n/**\n * 호스트의 판정을 **더한다.** 겹치면 어느 쪽이든 참이면 참이다 — 게이트는 「이 이름을 다룰 수 있나」를\n * 묻고, 두 출처 중 하나가 안다고 하면 다룰 수 있다.\n *\n * 한쪽으로 덮지 않는 이유: 덮으면 호스트가 자기 이름집합에 없는 등록 도구를 **조용히 잠근다.** 그러면\n * 대화면이 카테고리를 허용했는데 호출이 미등록으로 회신되고, 원인이 두 자리에 나뉘어 있어 못 찾는다.\n */\nexport function extendToolGate(base: ToolGate, extension: ToolGateExtension): ToolGate {\n  return {\n    filter: base.filter,\n    isRead: name => base.isRead(name) || !!extension.isRead?.(name),\n    isWrite: name => base.isWrite(name) || !!extension.isWrite?.(name),\n    isAction: name => base.isAction(name) || !!extension.isAction?.(name),\n    spec: name => base.spec(name) ?? extension.spec?.(name)\n  }\n}\n"]}

package/dist-server/service/assistant/summarize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 도구 결과를 화면·영속에 쓸 크기로 줄인다.
+ *
+ * 줄인 자리마다 **줄였다는 표시**를 남긴다(`…[+N chars]` · `…[+N items]` · `[Array(N)]`).
+ * 표시가 없으면 읽는 사람이 그것을 원본으로 믿는다.
+ */
+export declare function summarizeToolResult(value: any, depth?: number): any;

package/dist-server/service/assistant/summarize.js

@@ -0,0 +1,67 @@
+"use strict";
+/*
+ * Tool results, cut down to what a screen can hold.
+ *
+ * ── Why this is here and not in a product (2026-09-10) ───────────────────────────
+ * This came out of `board-ai`, and measuring the other consumer is what settled it: `twin-ai`
+ * passes `summarizeToolResult: v => v` — the identity function. So one product compressed its
+ * tool results before persisting them and the other did not, for no stated reason. That is the
+ * shape of a layer living in the wrong package: the second product does not decide differently,
+ * it just never gets the decision.
+ *
+ * ── ⚠ This is for the screen, never for a judgement ─────────────────────────────
+ * The output is depth- and length-limited, so it is **not evidence of what the model received**.
+ * A check that reads these summaries can pass while the model was handed `{}` — an un-awaited
+ * async builder did exactly that, and the screen still showed a successful call.
+ *
+ * What the model actually received is `AgenticLoopResult.groundedTexts`. Grounding already uses
+ * it, and anything that judges correctness must use it too.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeToolResult = summarizeToolResult;
+/** 문자열은 이 길이에서 자른다. 자른 사실과 잘린 양을 남긴다 — 조용히 짧아지지 않는다. */
+const MAX_STRING = 200;
+/** 배열은 이 개수까지 보이고 나머지는 수로 말한다. */
+const MAX_ITEMS = 5;
+/** 배열 안의 배열은 이 깊이에서 모양만 남긴다. */
+const MAX_ARRAY_DEPTH = 2;
+/** 객체는 이 깊이에서 키 이름만 남긴다. */
+const MAX_OBJECT_DEPTH = 3;
+/** 깊이 한계에서 남길 키 개수. */
+const MAX_KEYS = 6;
+/**
+ * 도구 결과를 화면·영속에 쓸 크기로 줄인다.
+ *
+ * 줄인 자리마다 **줄였다는 표시**를 남긴다(`…[+N chars]` · `…[+N items]` · `[Array(N)]`).
+ * 표시가 없으면 읽는 사람이 그것을 원본으로 믿는다.
+ */
+function summarizeToolResult(value, depth = 0) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'string') {
+        return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}…[+${value.length - MAX_STRING} chars]` : value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if (Array.isArray(value)) {
+        if (depth >= MAX_ARRAY_DEPTH)
+            return `[Array(${value.length})]`;
+        const out = value.slice(0, MAX_ITEMS).map(v => summarizeToolResult(v, depth + 1));
+        if (value.length > MAX_ITEMS)
+            out.push(`…[+${value.length - MAX_ITEMS} items]`);
+        return out;
+    }
+    if (typeof value === 'object') {
+        if (depth >= MAX_OBJECT_DEPTH) {
+            const keys = Object.keys(value).slice(0, MAX_KEYS).join(',');
+            return `{${keys}${Object.keys(value).length > MAX_KEYS ? ',…' : ''}}`;
+        }
+        const out = {};
+        for (const key of Object.keys(value)) {
+            out[key] = summarizeToolResult(value[key], depth + 1);
+        }
+        return out;
+    }
+    return undefined;
+}
+//# sourceMappingURL=summarize.js.map

package/dist-server/service/assistant/summarize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summarize.js","sourceRoot":"","sources":["../../../server/service/assistant/summarize.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;AAmBH,kDAwBC;AAzCD,wDAAwD;AACxD,MAAM,UAAU,GAAG,GAAG,CAAA;AACtB,kCAAkC;AAClC,MAAM,SAAS,GAAG,CAAC,CAAA;AACnB,gCAAgC;AAChC,MAAM,eAAe,GAAG,CAAC,CAAA;AACzB,4BAA4B;AAC5B,MAAM,gBAAgB,GAAG,CAAC,CAAA;AAC1B,uBAAuB;AACvB,MAAM,QAAQ,GAAG,CAAC,CAAA;AAElB;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,KAAU,EAAE,KAAK,GAAG,CAAC;IACvD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,KAAK,CAAC,MAAM,GAAG,UAAU,SAAS,CAAC,CAAC,CAAC,KAAK,CAAA;IAClH,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAA;IACzE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,IAAI,eAAe;YAAE,OAAO,UAAU,KAAK,CAAC,MAAM,IAAI,CAAA;QAC/D,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,mBAAmB,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAA;QACjF,IAAI,KAAK,CAAC,MAAM,GAAG,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,MAAM,GAAG,SAAS,SAAS,CAAC,CAAA;QAC/E,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,KAAK,IAAI,gBAAgB,EAAE,CAAC;YAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YAC5D,OAAO,IAAI,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,CAAA;QACvE,CAAC;QACD,MAAM,GAAG,GAAQ,EAAE,CAAA;QACnB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACrC,GAAG,CAAC,GAAG,CAAC,GAAG,mBAAmB,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;QACvD,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC","sourcesContent":["/*\n * Tool results, cut down to what a screen can hold.\n *\n * ── Why this is here and not in a product (2026-09-10) ───────────────────────────\n * This came out of `board-ai`, and measuring the other consumer is what settled it: `twin-ai`\n * passes `summarizeToolResult: v => v` — the identity function. So one product compressed its\n * tool results before persisting them and the other did not, for no stated reason. That is the\n * shape of a layer living in the wrong package: the second product does not decide differently,\n * it just never gets the decision.\n *\n * ── ⚠ This is for the screen, never for a judgement ─────────────────────────────\n * The output is depth- and length-limited, so it is **not evidence of what the model received**.\n * A check that reads these summaries can pass while the model was handed `{}` — an un-awaited\n * async builder did exactly that, and the screen still showed a successful call.\n *\n * What the model actually received is `AgenticLoopResult.groundedTexts`. Grounding already uses\n * it, and anything that judges correctness must use it too.\n */\n\n/** 문자열은 이 길이에서 자른다. 자른 사실과 잘린 양을 남긴다 — 조용히 짧아지지 않는다. */\nconst MAX_STRING = 200\n/** 배열은 이 개수까지 보이고 나머지는 수로 말한다. */\nconst MAX_ITEMS = 5\n/** 배열 안의 배열은 이 깊이에서 모양만 남긴다. */\nconst MAX_ARRAY_DEPTH = 2\n/** 객체는 이 깊이에서 키 이름만 남긴다. */\nconst MAX_OBJECT_DEPTH = 3\n/** 깊이 한계에서 남길 키 개수. */\nconst MAX_KEYS = 6\n\n/**\n * 도구 결과를 화면·영속에 쓸 크기로 줄인다.\n *\n * 줄인 자리마다 **줄였다는 표시**를 남긴다(`…[+N chars]` · `…[+N items]` · `[Array(N)]`).\n * 표시가 없으면 읽는 사람이 그것을 원본으로 믿는다.\n */\nexport function summarizeToolResult(value: any, depth = 0): any {\n  if (value === null || value === undefined) return value\n  if (typeof value === 'string') {\n    return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}…[+${value.length - MAX_STRING} chars]` : value\n  }\n  if (typeof value === 'number' || typeof value === 'boolean') return value\n  if (Array.isArray(value)) {\n    if (depth >= MAX_ARRAY_DEPTH) return `[Array(${value.length})]`\n    const out = value.slice(0, MAX_ITEMS).map(v => summarizeToolResult(v, depth + 1))\n    if (value.length > MAX_ITEMS) out.push(`…[+${value.length - MAX_ITEMS} items]`)\n    return out\n  }\n  if (typeof value === 'object') {\n    if (depth >= MAX_OBJECT_DEPTH) {\n      const keys = Object.keys(value).slice(0, MAX_KEYS).join(',')\n      return `{${keys}${Object.keys(value).length > MAX_KEYS ? ',…' : ''}}`\n    }\n    const out: any = {}\n    for (const key of Object.keys(value)) {\n      out[key] = summarizeToolResult(value[key], depth + 1)\n    }\n    return out\n  }\n  return undefined\n}\n"]}

package/dist-server/service/index.d.ts

@@ -4,3 +4,4 @@ export * from './providers/index.js';
 export * from './utils/index.js';
 export * from './tool-registry/index.js';
 export * from './agentic-loop/index.js';
+export * from './assistant/index.js';

package/dist-server/service/index.js

@@ -7,4 +7,5 @@ tslib_1.__exportStar(require("./providers/index.js"), exports);
 tslib_1.__exportStar(require("./utils/index.js"), exports);
 tslib_1.__exportStar(require("./tool-registry/index.js"), exports);
 tslib_1.__exportStar(require("./agentic-loop/index.js"), exports);
+tslib_1.__exportStar(require("./assistant/index.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist-server/service/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/service/index.ts"],"names":[],"mappings":";;;AAAA,qDAA0B;AAC1B,uDAA4B;AAC5B,+DAAoC;AACpC,2DAAgC;AAChC,mEAAwC;AACxC,kEAAuC","sourcesContent":["export * from './types.js'\nexport * from './factory.js'\nexport * from './providers/index.js'\nexport * from './utils/index.js'\nexport * from './tool-registry/index.js'\nexport * from './agentic-loop/index.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../server/service/index.ts"],"names":[],"mappings":";;;AAAA,qDAA0B;AAC1B,uDAA4B;AAC5B,+DAAoC;AACpC,2DAAgC;AAChC,mEAAwC;AACxC,kEAAuC;AACvC,+DAAoC","sourcesContent":["export * from './types.js'\nexport * from './factory.js'\nexport * from './providers/index.js'\nexport * from './utils/index.js'\nexport * from './tool-registry/index.js'\nexport * from './agentic-loop/index.js'\nexport * from './assistant/index.js'\n"]}

package/dist-server/service/tool-registry/registry.js

@@ -15,6 +15,25 @@ const categories = new Map();
  * 카테고리 등록. tool name 충돌 시 throw, 이름 중복 등록 시 덮어쓰기 + warn.
  */
 function registerToolCategory(category) {
+    /*
+     * 지침 없는 카테고리는 **등록하지 않는다.**
+     *
+     * 도구 목록만 보낸 모델이 「불러야 할 때 부른다」를 맞히지 못한 사고가 있었다 — 조치 요청에
+     * `proposeAction` 을 부르지 않고 「제안해 두었습니다」라고 답해, 사용자에게 없는 버튼을 누르라고
+     * 안내했다. 화면에는 아무 일도 없었고 오류도 나지 않았다(§`ToolCategory.guidance`).
+     *
+     * 그 뒤로 규율을 적는 자리를 만들었지만 **선택이었다.** 선택인 규율은 그 사고를 아는 사람만
+     * 채운다. 여기서 거절하는 이유가 그것이다 — 빠진 것을 부팅에서 만든 사람이 보고, 모델이 헛말을
+     * 한 뒤에 사용자가 보지 않는다.
+     *
+     * 빈 문자열·공백도 거절한다. 통과시키면 이 검사가 형식이 되고, 형식이 된 검사는 없는 것과 같다.
+     */
+    if (!String(category.guidance ?? '').trim()) {
+        throw new Error(`[ai-client-base/tool-registry] category '${category.name}' has no guidance. ` +
+            'Tool descriptions say what a tool does; guidance says when the model must call one. ' +
+            'Without it a model answers as though it called a tool it did not, and nothing errors. ' +
+            'Write the rules for these tools in `guidance` — the side that registers them owns them.');
+    }
     if (categories.has(category.name)) {
         console.warn(`[board-ai/tool-registry] category '${category.name}' already registered — overwriting. ` +
             `(dev hot-reload 시 정상이지만 운영 환경에서 발생하면 buildup bug)`);