@things-factory/twin-ai 10.0.0-zeta.12

package/dist-server/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @things-factory/twin-ai — operato-twin 디지털트윈용 AI 어시스턴트(서버-only).
+ *
+ * 접지 대화(P1): "정상?/뭐 봐야 해?" 를 트윈 실데이터(attentions/state)를 도구로 조회해 답한다(환각 금지).
+ * ai-client-base(프로바이더 추상화) + headless-twin(TwinEngine 스냅샷) 위에 트윈 도메인 어댑터만 얹는다.
+ * 설계 SoT: operato-twin/design/plans/twin-ai-assistant.md
+ */
+export * from './service/index.js';

package/dist-server/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+/**
+ * @things-factory/twin-ai — operato-twin 디지털트윈용 AI 어시스턴트(서버-only).
+ *
+ * 접지 대화(P1): "정상?/뭐 봐야 해?" 를 트윈 실데이터(attentions/state)를 도구로 조회해 답한다(환각 금지).
+ * ai-client-base(프로바이더 추상화) + headless-twin(TwinEngine 스냅샷) 위에 트윈 도메인 어댑터만 얹는다.
+ * 설계 SoT: operato-twin/design/plans/twin-ai-assistant.md
+ */
+tslib_1.__exportStar(require("./service/index.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist-server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../server/index.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,6DAAkC","sourcesContent":["/**\n * @things-factory/twin-ai — operato-twin 디지털트윈용 AI 어시스턴트(서버-only).\n *\n * 접지 대화(P1): \"정상?/뭐 봐야 해?\" 를 트윈 실데이터(attentions/state)를 도구로 조회해 답한다(환각 금지).\n * ai-client-base(프로바이더 추상화) + headless-twin(TwinEngine 스냅샷) 위에 트윈 도메인 어댑터만 얹는다.\n * 설계 SoT: operato-twin/design/plans/twin-ai-assistant.md\n */\nexport * from './service/index.js'\n"]}

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

@@ -0,0 +1,58 @@
+import type { AITool } from '@things-factory/ai-client-base';
+export declare const TOOLS: AITool[];
+/** 도구 실행 — canonical 소스(라이브 커널 스냅샷·이벤트 저널)에서 직접(in-process).
+ *  export: P0 테스트가 접지·propose-only 게이트를 도구 단위로 검증(런타임 동작 무변경 — 테스트 이음매). */
+export declare function execTool(name: string, args: Record<string, any>, domainId?: string): Promise<unknown>;
+export interface TwinAiAnswer {
+    reply: string;
+    toolCalls: string[];
+    /** 답이 언급한 공간 앵커(attentions/signals 파생) — 클라가 칩·하이라이트로 공간과 연결.
+     *  kind 는 클라 focus 표준(location|mover|order). attention 은 그 신호(의미·조치)로, 클라가
+     *  공간 진입 시 entity360 상단에 원인·권고 조치를 그대로 재현하도록 함께 실어 보낸다. */
+    anchors: {
+        kind: string;
+        id: string;
+        attention?: any;
+    }[];
+    /** AI 가 제안한 조치(실행 아님 — 사용자 확인 후 dispatchTwinCommand 로 실행). 살아있는 시스템 게이트. */
+    proposedActions: {
+        command: string;
+        args: any;
+        label: string;
+        reason?: string;
+    }[];
+    /** zero-to-twin 초안(생성 아님 — 사용자 확인 후 saveTwinInstance+start). §12 프로비저닝 게이트. */
+    proposedProvisions: {
+        system: string;
+        instanceId: string;
+        label: string;
+        board: any;
+        scenario: any;
+        space: any;
+        summary?: any;
+        warnings?: string[];
+        viability?: any;
+        explanation?: any;
+    }[];
+    /** 접지 가드 — reply 가 언급했으나 근거(도구 출력·사용자 입력·이력)에 없는 엔티티 id(환각 후보). 비면 접지 정상. */
+    groundingWarnings: string[];
+}
+export declare function extractIdTokens(s: string): Set<string>;
+/** reply 언급 id − 근거코퍼스 id = 미확인(환각 후보). */
+export declare function checkGrounding(reply: string, groundedCorpus: string): string[];
+/** 도구 결과에서 공간 앵커 수집(중복 제거). 두 경로 모두 커버: queryAttentions→out.attentions(full),
+ *  summarizeStatus→out.signals(trimmed). kind 는 클라 focus 표준으로(노드=location), 신호(원인·조치)를
+ *  attention 으로 함께 실어 공간 진입 시 재현되게 한다. attentions(full)가 signals(trimmed)를 덮도록 뒤에 둔다. */
+export declare function collectAnchors(out: any, into: Map<string, {
+    kind: string;
+    id: string;
+    attention?: any;
+}>): void;
+/**
+ * 접지된 단발 질의 — 완주 후 반환. tool 루프는 단순(단일 read 도구, 최대 4 iteration).
+ * Gemini providerMeta(thoughtSignature) 는 tool_use turn 에 반드시 echo(안 하면 400).
+ */
+export declare function twinAiAsk(instanceId: string, message: string, domainId?: string, history?: {
+    role: string;
+    text: string;
+}[], locale?: string): Promise<TwinAiAnswer>;

package/dist-server/service/assistant.js

@@ -0,0 +1,422 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOLS = void 0;
+exports.execTool = execTool;
+exports.extractIdTokens = extractIdTokens;
+exports.checkGrounding = checkGrounding;
+exports.collectAnchors = collectAnchors;
+exports.twinAiAsk = twinAiAsk;
+const ai_client_base_1 = require("@things-factory/ai-client-base");
+/* 도구 실행은 관심사별 모듈에 위임(execTool 은 디스패치만). assistant 는 오케스트레이션(agentic 루프)에 집중. */
+const zero_to_twin_ts_1 = require("./zero-to-twin.js");
+const read_predict_ts_1 = require("./read-predict.js");
+/*
+ * 트윈 AI 어시스턴트 — 첫 수직 슬라이스(P1): 접지된 read Q&A("정상?/뭐 봐야 해?").
+ * 설계 SoT: operato-twin/design/plans/twin-ai-assistant.md
+ *
+ * 사상: AI 도구 = 트윈 canonical 연산 1:1(무방언). 답은 도구로 조회한 사실에만 근거(grounded, 환각 금지).
+ * 첫 도구 = queryAttentions(스냅샷의 요약 주목신호 — 집계 API·full-state 덤프 없이 "정상?" 접지).
+ * LLM 프로바이더는 ai-client-base 추상화(config.aiClient) 재사용. 완주 후 반환(스트리밍은 후행).
+ */
+const SYSTEM_PROMPT = `당신은 operato-twin 디지털 트윈의 운영 어시스턴트다.
+규칙:
+- 반드시 도구로 조회한 사실에만 근거해 답한다. 지어내지 말 것. 데이터가 없으면 "데이터 없음"이라고 답한다.
+- **"정상인가?/지금 어때?/괜찮아?" 류엔 summarizeStatus 로 전반 health(normal|watch|attention|critical)와 봐야 할 신호를 한눈에 받아** 초보자 언어로 전한다: normal 이면 "정상", 아니면 무엇이 문제인지·어떡할지(suggestedAction)를 평이하게. 기술 title 대신 kind·severity 로 옮겨 말한다.
+- **원인을 묻는 질문("작업 지연의 원인은?", "왜 정체돼?")에는 queryAttentions 와 queryState 를 함께 조회해 여러 신호를 상관지어 근원을 추론한다.**
+  예: 설비 고장(mover status=down) → 그 노드(weld-station 등)의 점유율 상승·태스크 정체 → 하류 오더 지연. **인과 사슬을 "A → B → C" 형태로 근거와 함께 제시**한다.
+  추론은 조회한 데이터로만 뒷받침하고, 데이터로 단정 못 하면 "데이터로는 여기까지"라고 밝힌다(그럴듯한 추측 금지).
+- **"언제부터/이력/시점" 질문에는 traceJournal 도구로 이벤트 저널 타임라인을 조회한다**(eventType: 'equipment.status'=설비 고장/복구 이력, 'order.status'=오더, 'task.status'=작업). 문제가 **시작된 시점·이벤트**를 특정해 "T 시점 welder-2 고장 이후 누적" 처럼 시간 축으로 근원을 짚는다.
+- **미래를 묻는 질문("앞으로 어떻게 돼?/언제 회복돼?/전망은?")에는 forecast 도구를 쓴다.** 현재를 여러 번 복제(fork)해 미래 확률을 변주한 **몬테카를로 예측**이다("현재 조건 지속" 가정 명시). now 대비 forecast 의 **p50(중앙값)·p90(비관 시나리오)**로 전망하고(단정 대신 분포로 정직하게 — 예: "p50이면 이 정도, p90 최악엔 포화"), **recovery(회복 예상 시점)**를 함께 전한다.
+- **"몇 대 필요?/최적 자원" 질문에는 optimizeResource 도구를 쓴다.** 자원 대수를 0..N 스윕해 각 대수의 정체 지표(tasks·occupancy)를 비교하고, **개선이 꺾이는 지점(수확체감)** 또는 목표 충족 **최소 대수**를 짚는다("N대부터는 효과 미미" 처럼 marginal gain 명시). 목표 기준이 모호하면 지표 추세로 판단하거나 되묻는다.
+- **구성을 바꾼 가정 질문("지게차 +1이면?/용량 늘리면 나아져?")에는 whatIf 도구를 쓴다.** baseline(무변경) vs modified(변경) 를 현재에서 각각 fork·투영해 비교하고, delta(occupancy/tasks/orders 차이)로 **개선/무변화**를 판단한다. 대상 노드·무버 kind/id 가 필요하면 queryState 로 먼저 확인. "현재 조건 지속 + 그 변경" 가정임을 명시하고, 원본은 무간섭(fork).
+- 근거를 함께 제시한다: 주목신호의 kind·severity·anchor(어느 노드/무버/오더)·since. suggestedAction 이 있으면 "권고: …"로 알리되, 직접 실행하지는 않는다.
+- **조치 실행 요청("그 오더 보류해줘/재개해줘")에는 절대 직접 실행하지 말고 proposeAction 도구로 "제안"만 한다**(command·args·label·reason). 실제 실행은 **사용자가 확인 버튼으로** 한다. 제안 후 답에 "실행하려면 아래에서 확인하세요"라고 안내한다. attentions 의 suggestedAction 을 그대로 제안에 쓸 수 있다.
+  - **지원되는 라이브 커맨드는 이것뿐이다(다른 command 를 지어내지 말 것)**: order.hold / order.resume / order.release / attention.ack / resource.hold(계획 정지) / resource.resume / resource.down(고장 주입) / resource.repair(수리) / **resource.add(자원 추가 — args:{kind, homeNode, count})**. 목록 밖은 제안 금지.
+  - **"지게차 추가해줘/한 대 더 투입"류에는 resource.add 를 proposeAction 으로 제안한다(실제 반영됨).** homeNode 는 queryState 로 적절한 노드(입고 도크 등)를 골라 채운다. "효과가 어떨까?/추가하면 나아져?"처럼 **가정·검토**면 먼저 whatIf 로 미리보기하고, "추가해줘"처럼 **실행 의도**면 resource.add 를 제안한다.
+  - **자원 제거·노드/구조 변경은 아직 커맨드가 아니다(미지원).** 그런 요청엔 "새 구성으로 트윈을 다시 만들어야 한다(프로비저닝)"고 정직하게 안내한다. **없는 기능을 실행되는 것처럼 말하지 말 것.**
+- **사용자가 무엇을 만들 수 있는지 모르거나("트윈 뭐 만들 수 있어?", "우리 상황엔 뭐가 맞아?") 시스템 선택이 모호하면, 먼저 listTwinSystems 로 선택지(창고/야드/공장)와 각각 다루는 것을 보여주고, 사용자 상황(취급물·공정)을 물어 맞는 시스템을 고른 뒤 아래 zero-to-twin 으로 잇는다.** 초보의 첫 장벽은 "무엇을 만들지 모름"이다 — 대신 골라주지 말고 골라내도록 돕는다.
+- **새 트윈을 만들어 달라는 요청("이런 창고/야드/공장 만들어줘", "~를 시뮬레이션하고 싶어")에는 zero-to-twin 순서를 따른다**:
+  1. 먼저 **listTwinTypes** 로 해당 시스템(wms=창고/yms=야드/mes=제조)의 **가능한 노드/무버 타입 팔레트를 확인**한다. 타입을 지어내지 말 것 — 카탈로그 어휘만 쓴다(모르면 listTwinTypes 로 확인).
+  2. **규모·구조가 모호하면(예: "창고 만들어줘"만 말함) 먼저 suggestArchetype(system, scale) 로 완비된 합리적 기본 구성(입고·보관·출고·자원 다 포함 → 실제 작동)을 받는다.** 사용자가 규모를 말했으면 scale(small/medium/large)로, 특이사항을 말했으면 반환된 nodes/movers 를 조정한다. 그대로 쓰든 조정하든 **어떤 가정을 했는지 명시**한다. (구체적으로 다 말한 요청이면 그 명세를 그대로 쓴다.)
+  3. **proposeTwin** 도구로 구조·좌표·시나리오 **초안을 "제안"만** 한다(직접 생성 아님). 좌표는 도구가 자동 배치한다. 제안 후 **proposeTwin 결과의 explanation.parts(각 {label, count, role})로** 무엇을 잡았는지 사용자 언어로 평이하게 전한다(spaceCount·resourceCount 로 요약). **기술 키(typeKey: dock-ship 등)는 절대 노출하지 말고 label(출고 도크 등)을 사용자 언어로 옮겨 말한다.** "아래에서 확인하면 생성됩니다"라고 안내하고, 실제 생성은 사용자가 확인 버튼으로.
+  4. **proposeTwin 결과의 viability 를 반드시 확인한다.** ok=false 면 issues[].message(영어 canonical)를 **사용자 언어로 옮겨** 전문용어 없이 짚고 고침을 제안한다 — 예(no-active-resource): "지금은 물건을 옮길 지게차가 없어 트윈이 멈춰 있어요. 몇 대 넣을까요?" (없는 기능을 되는 것처럼 말하지 말 것.)
+  5. **이미 제안한 트윈을 사용자가 바꿔달라고 하면("더 크게/작게", "지게차 빼줘/5대로", "보관 늘려줘") refineTwin 을 쓴다.** 직전 제안의 nodes/movers 를 그대로 넘기고 변경(scale/setCounts/removeKinds)만 지정한다 — **개수를 직접 재계산하지 말 것(도구가 계산).** 결과의 explanation·viability 를 다시 평이하게 전한다. 새로 처음부터 만드는 게 아니라 다듬는 것이다.
+- 현장 목표(SLA·목표 처리량 등)가 설정돼 있지 않으면 "현재 도메인 판단 기준"이라고 명시한다(목표 대비 정상 여부는 아직 판단 불가).
+- **답변은 사용자가 쓴 언어로 한다**(한국어로 물으면 한국어, 영어면 영어). 도구가 돌려준 영어 message·영어 code·카탈로그 label 은 사용자 언어로 옮겨 전한다. 간결하게.`;
+/* export: P0 테스트 토대가 도구 스펙을 직접 검증(런타임 동작 무변경 — 테스트 이음매). */
+exports.TOOLS = [
+    {
+        name: 'summarizeStatus',
+        description: '"지금 괜찮아?/어때?/정상?" 류에 트윈 전반 상태를 한눈에 반환한다(운영측 만만함). health(normal|watch|attention|critical) + severity별 counts + signals[{severity,kind,title,anchor,suggestedAction}]. health·kind·severity 는 언어 중립 — 초보자 언어로 옮겨 전하고, suggestedAction 있으면 권고로. 개별 신호를 깊이 파려면 queryState/traceJournal 로.',
+        parameters: {
+            type: 'object',
+            properties: { instanceId: { type: 'string', description: '트윈 인스턴스 id' } },
+            required: ['instanceId']
+        }
+    },
+    {
+        name: 'queryAttentions',
+        description: '현재 트윈 스냅샷의 주목신호(봐야 할 것) 목록을 반환한다. 각 항목: kind, severity(low|medium|high|critical), state(active|acknowledged|cleared), title, detail, anchor{nodeId,moverId,orderId}, since(simClockMs), suggestedAction{command,label}. 요약이므로 전체 상태를 덤프하지 않고 이 도구로 판단한다.',
+        parameters: {
+            type: 'object',
+            properties: {
+                instanceId: { type: 'string', description: '트윈 인스턴스 id' }
+            },
+            required: ['instanceId']
+        }
+    },
+    {
+        name: 'queryState',
+        description: '현재 트윈 스냅샷의 요약 상태(전체 덤프 아님) — 원인 추론용. 반환: nodes[{id,type,occupancy,capacity}](점유율=병목 신호), movers[{id,kind,status}](status=down 이면 설비 고장), taskCounts(status별 수), orderCounts(status별 수). attentions 와 상관지어 인과를 추론한다.',
+        parameters: {
+            type: 'object',
+            properties: {
+                instanceId: { type: 'string', description: '트윈 인스턴스 id' }
+            },
+            required: ['instanceId']
+        }
+    },
+    {
+        name: 'forecast',
+        description: '현재 상태를 복제(fork)해 horizonMinutes 뒤까지 굴린 투영(현재 조건·부하·고장/수리 일정 지속 가정). 반환: now·projected 각각 { occupancy(총점유), orders, tasks, moversDown }. "앞으로/언제 회복/전망" 질문에 사용. 원본 라이브 무간섭(fork 격리).',
+        parameters: {
+            type: 'object',
+            properties: {
+                instanceId: { type: 'string', description: '트윈 인스턴스 id' },
+                horizonMinutes: { type: 'number', description: '예측 지평(분). 기본 30, 1~120.' }
+            },
+            required: ['instanceId']
+        }
+    },
+    {
+        name: 'whatIf',
+        description: '구성을 바꾼 가상 시나리오를 현재에서 fork해 비교("지게차 +1이면?", "용량 늘리면?"). baseline(무변경) vs modified 를 horizonMinutes 까지 굴려 비교. 반환: baseline·modified·delta 의 {occupancy,orders,tasks,moversDown}. 원본 무간섭(fork). 대상 kind/nodeId 는 queryState 로 확인.',
+        parameters: {
+            type: 'object',
+            properties: {
+                instanceId: { type: 'string', description: '트윈 인스턴스 id' },
+                horizonMinutes: { type: 'number', description: '기본 30, 1~120' },
+                addMovers: {
+                    type: 'array',
+                    description: '추가할 자원(무버). 예: [{"kind":"forklift","homeNode":"dock-recv","count":1}]',
+                    items: {
+                        type: 'object',
+                        properties: { kind: { type: 'string' }, homeNode: { type: 'string' }, count: { type: 'number' } },
+                        required: ['kind', 'homeNode']
+                    }
+                },
+                setCapacity: {
+                    type: 'array',
+                    description: '노드 용량 변경. 예: [{"nodeId":"bin-1","capacity":200}]',
+                    items: {
+                        type: 'object',
+                        properties: { nodeId: { type: 'string' }, capacity: { type: 'number' } },
+                        required: ['nodeId', 'capacity']
+                    }
+                }
+            },
+            required: ['instanceId']
+        }
+    },
+    {
+        name: 'optimizeResource',
+        description: '자원(무버) 대수를 0..maxCount 로 바꿔가며 각각 fork·투영(동일 조건, 무버만 증가)해 정체 지표를 비교한다. "정체 해소에 몇 대 필요?"의 근거. 반환: sweep[{added, occupancy, tasks, orders}]. AI 가 수확체감 꺾임/목표 충족 최소 대수를 판단.',
+        parameters: {
+            type: 'object',
+            properties: {
+                instanceId: { type: 'string', description: '트윈 인스턴스 id' },
+                kind: { type: 'string', description: '추가할 자원 종류(예: forklift, welder)' },
+                homeNode: { type: 'string', description: '자원 배치 노드 id' },
+                maxCount: { type: 'number', description: '최대 추가 대수(기본 5, 1~10)' },
+                horizonMinutes: { type: 'number', description: '기본 30, 1~120' }
+            },
+            required: ['instanceId', 'kind', 'homeNode']
+        }
+    },
+    {
+        name: 'traceJournal',
+        description: '이벤트 저널(append-only)의 최근 타임라인을 조회한다. "언제부터/이력/시점" 질문의 근거. eventType 로 필터(equipment.status=설비 고장/복구, order.status=오더, task.status=작업). 반환: events[{revision, eventTime, eventType, info}] 시간 오름차순.',
+        parameters: {
+            type: 'object',
+            properties: {
+                instanceId: { type: 'string', description: '트윈 인스턴스 id' },
+                eventType: { type: 'string', description: "필터: 'equipment.status' | 'order.status' | 'task.status' 등(생략 시 전체)" },
+                limit: { type: 'number', description: '최근 N건(기본 25, 1~50)' }
+            },
+            required: ['instanceId']
+        }
+    },
+    {
+        name: 'proposeAction',
+        description: '사용자에게 조치 실행을 "제안"한다(직접 실행 아님 — 사용자가 확인 후 실행). "~보류해/재개해/고장/수리/추가해" 같은 요청에 쓴다. **지원 command 는 이것뿐(그 외 발명 금지)**: order.hold / order.resume / order.release / attention.ack / resource.hold / resource.resume / resource.down / resource.repair / resource.add. resource.add 의 args 는 {kind, homeNode, count} — 라이브 트윈에 자원(무버)을 실제로 추가한다("지게차 추가해줘"). **자원 제거·노드/구조 변경은 미지원 — 그런 요청엔 재프로비저닝을 안내.**',
+        parameters: {
+            type: 'object',
+            properties: {
+                command: { type: 'string', description: '커맨드 타입(order.hold/order.resume/order.release/attention.ack 등)' },
+                args: { type: 'object', description: '커맨드 인자(예: {"orderId":"order-7"})' },
+                label: { type: 'string', description: '사람용 짧은 설명(예: "order-7 보류 해제")' },
+                reason: { type: 'string', description: '이 조치를 제안하는 근거' }
+            },
+            required: ['command', 'label']
+        }
+    },
+    {
+        name: 'listTwinSystems',
+        description: '사용자가 무엇을 트윈으로 만들 수 있는지 모르거나("트윈 뭐 만들 수 있어?") 어떤 시스템이 자기 상황에 맞는지 물을 때, 가능한 시스템(wms=창고·yms=야드·mes=제조)과 각각 다루는 노드/자원을 반환한다. 이걸로 선택지를 보여주고 사용자 상황을 물어 맞는 시스템을 고른 뒤 suggestArchetype→proposeTwin 으로 잇는다. 파라미터 없음. 반환: { systems:[{system,label,nodeTypes,resourceTypes}] }.',
+        parameters: { type: 'object', properties: {} }
+    },
+    {
+        name: 'suggestArchetype',
+        description: '규모·구조가 모호한 요청("창고 만들어줘", "공장 하나 시뮬레이션")에 쓸, 시스템별 합리적 기본 트윈 구성(입고·보관·출고·자원 완비 → 실제로 작동)을 카탈로그 타입으로 반환한다. 반환된 nodes/movers 를 proposeTwin 에 그대로 넘기거나 사용자가 말한 규모/특이사항에 맞게 조정한다. 초보 입력을 완전한 트윈으로 만드는 지름길. 반환: { system, scale, nodes[{id,type}], movers[{kind,homeNode,count}], note }.',
+        parameters: {
+            type: 'object',
+            properties: {
+                system: { type: 'string', description: "'wms'(창고) | 'yms'(야드) | 'mes'(제조)" },
+                scale: { type: 'string', description: "규모: 'small' | 'medium'(기본) | 'large'. 사용자 표현(작은/큰 등)에 맞춰 고른다." }
+            },
+            required: ['system']
+        }
+    },
+    {
+        name: 'listTwinTypes',
+        description: '트윈을 새로 만들 때 쓸 수 있는 노드/무버 타입 팔레트를 커널 카탈로그(SSOT)에서 반환한다. 새 트윈 생성(proposeTwin) 전에 반드시 이 도구로 가능한 타입을 확인한다(타입 발명 금지). 반환: { system, label, nodeTypes[{key,label}], moverTypes[{key,label}] }.',
+        parameters: {
+            type: 'object',
+            properties: {
+                system: { type: 'string', description: "'wms'(창고) | 'yms'(야드) | 'mes'(제조)" }
+            },
+            required: ['system']
+        }
+    },
+    {
+        name: 'proposeTwin',
+        description: '새 트윈 인스턴스의 구조·좌표·시나리오 초안을 "제안"한다(직접 생성 아님 — 사용자가 확인 후 생성). zero-to-twin. 노드/무버 타입은 listTwinTypes 팔레트에서만 고른다. 좌표(layout)는 서버가 타입별 흐름 순서로 자동 배치하므로 지정하지 않는다. 시나리오(자극)를 생략하면 시스템 기본(입고 도착+출고 오더)을 붙인다.',
+        parameters: {
+            type: 'object',
+            properties: {
+                system: { type: 'string', description: "'wms' | 'yms' | 'mes'" },
+                instanceId: { type: 'string', description: '새 인스턴스 id(영문/숫자/하이픈, 예: "wh-seoul-1"). 사용자가 안 정하면 의미있는 값 제안.' },
+                label: { type: 'string', description: '사람용 이름(예: "서울 물류창고")' },
+                nodes: {
+                    type: 'array',
+                    description: '로케이션 노드. type 은 listTwinTypes 의 nodeTypes 에서만. id 는 유일.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            type: { type: 'string', description: '카탈로그 노드 타입 key' },
+                            capacity: { type: 'number', description: '수용량(생략 시 0=무제한 취급)' }
+                        },
+                        required: ['id', 'type']
+                    }
+                },
+                movers: {
+                    type: 'array',
+                    description: '자원(무버). kind 는 listTwinTypes 의 moverTypes 에서만. homeNode 는 위 nodes 의 id.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            kind: { type: 'string', description: '카탈로그 무버 타입 key' },
+                            homeNode: { type: 'string', description: '초기 배치 노드 id' },
+                            count: { type: 'number', description: '대수(기본 1)' }
+                        },
+                        required: ['kind', 'homeNode']
+                    }
+                }
+            },
+            required: ['system', 'instanceId', 'nodes']
+        }
+    },
+    {
+        name: 'refineTwin',
+        description: '이미 제안된 트윈을 사용자 요청대로 다듬어 재제안한다("더 크게/작게", "지게차 빼줘/5대로", "보관 6곳으로"). 직전 제안의 nodes/movers 를 그대로 넘기고 변경만 지정한다 — 카운트 계산은 도구가 하니 직접 재계산하지 말 것. 반환은 proposeTwin 과 동형(draft·viability·explanation·warnings).',
+        parameters: {
+            type: 'object',
+            properties: {
+                system: { type: 'string', description: "'wms'|'yms'|'mes' (직전 제안과 동일)" },
+                instanceId: { type: 'string', description: '직전 제안의 instanceId' },
+                label: { type: 'string', description: '이름(직전과 동일)' },
+                nodes: {
+                    type: 'array',
+                    description: '직전 제안의 현재 노드 [{id,type}]',
+                    items: { type: 'object', properties: { id: { type: 'string' }, type: { type: 'string' } }, required: ['id', 'type'] }
+                },
+                movers: {
+                    type: 'array',
+                    description: '직전 제안의 현재 무버 [{kind,homeNode,count}]',
+                    items: {
+                        type: 'object',
+                        properties: { kind: { type: 'string' }, homeNode: { type: 'string' }, count: { type: 'number' } },
+                        required: ['kind', 'homeNode']
+                    }
+                },
+                scale: { type: 'string', description: "'up'(더 크게) | 'down'(더 작게) — 전체 규모를 배로/반으로" },
+                setCounts: {
+                    type: 'array',
+                    description: '특정 구성요소 개수 지정. 예: [{"key":"storage","count":6}] 또는 [{"key":"forklift","count":5}]. count 0 = 제거.',
+                    items: { type: 'object', properties: { key: { type: 'string' }, count: { type: 'number' } }, required: ['key', 'count'] }
+                },
+                removeKinds: { type: 'array', description: '통째로 뺄 타입/자원 키. 예: ["forklift"]', items: { type: 'string' } }
+            },
+            required: ['system', 'instanceId', 'nodes']
+        }
+    }
+];
+/* 관심사별 모듈 분리(모놀리스 분할) — execTool 이 위임한다:
+ *  · zero-to-twin.ts : 저작(listTwinSystems·suggestArchetype·listTwinTypes·proposeTwin·refineTwin·viability·explain)
+ *  · read-predict.ts : 관측·예측(queryAttentions·queryState·traceJournal·forecast·whatIf·optimizeResource) */
+/** 도구 실행 — canonical 소스(라이브 커널 스냅샷·이벤트 저널)에서 직접(in-process).
+ *  export: P0 테스트가 접지·propose-only 게이트를 도구 단위로 검증(런타임 동작 무변경 — 테스트 이음매). */
+async function execTool(name, args, domainId) {
+    if (name === 'summarizeStatus')
+        return (0, read_predict_ts_1.summarizeStatus)(args); // → read-predict.ts (운영측 만만함: health 한눈에)
+    if (name === 'queryAttentions')
+        return (0, read_predict_ts_1.queryAttentions)(args); // → read-predict.ts
+    if (name === 'queryState')
+        return (0, read_predict_ts_1.queryState)(args); // → read-predict.ts
+    if (name === 'forecast')
+        return (0, read_predict_ts_1.forecast)(args); // → read-predict.ts (몬테카를로)
+    if (name === 'whatIf')
+        return (0, read_predict_ts_1.whatIf)(args); // → read-predict.ts (구성 변주)
+    if (name === 'optimizeResource')
+        return (0, read_predict_ts_1.optimizeResource)(args); // → read-predict.ts (대수 스윕)
+    if (name === 'traceJournal')
+        return (0, read_predict_ts_1.traceJournal)(args, domainId); // → read-predict.ts (저널)
+    if (name === 'proposeAction') {
+        // 실행하지 않는다 — 제안만 기록. 실제 실행은 사용자 확인 후 dispatchTwinCommand(살아있는 시스템 게이트).
+        return { proposed: true, note: 'Proposal recorded (not executed). The user executes it via the confirm button.' };
+    }
+    if (name === 'listTwinSystems')
+        return (0, zero_to_twin_ts_1.listTwinSystems)(); // → zero-to-twin.ts (시작 이전 안내)
+    if (name === 'suggestArchetype')
+        return (0, zero_to_twin_ts_1.suggestArchetype)(args); // → zero-to-twin.ts (모호 입력→완비 기본)
+    if (name === 'listTwinTypes')
+        return (0, zero_to_twin_ts_1.listTwinTypes)(args); // → zero-to-twin.ts (카탈로그 접지)
+    if (name === 'proposeTwin')
+        return (0, zero_to_twin_ts_1.proposeTwin)(args); // → zero-to-twin.ts (propose-only + viability)
+    if (name === 'refineTwin')
+        return (0, zero_to_twin_ts_1.refineTwin)(args); // → zero-to-twin.ts (다듬기 델타 적용 후 재제안)
+    return { error: `unknown tool: ${name}` };
+}
+/* ── 접지 가드(무환각 코드 강제) ─────────────────────────────────────────────
+ * LLM 은 tool_result(JSON)·사용자 메시지·이력만 근거로 가진다. reply 가 언급한 엔티티 id 가
+ * 그 근거에 없으면 = 환각 후보. id 관례(하이픈 포함 소문자-영숫자: fk-1·weld-station·order-7)로
+ * 보수적으로 추출(하이픈 없는 일반어·한국어·p90·gtin 은 매칭 안 함) → 근거집합과 차집합.
+ * reply 는 변형하지 않고 구조화 경고만 노출(비파괴·클라 렌더·향후 재생성 토대). */
+const ID_TOKEN = /[a-z][a-z0-9]*(?:-[a-z0-9]+)+/g;
+function extractIdTokens(s) {
+    const out = new Set();
+    for (const m of (s ?? '').matchAll(ID_TOKEN))
+        out.add(m[0]);
+    return out;
+}
+/** reply 언급 id − 근거코퍼스 id = 미확인(환각 후보). */
+function checkGrounding(reply, groundedCorpus) {
+    const grounded = extractIdTokens(groundedCorpus);
+    const mentioned = extractIdTokens(reply);
+    return [...mentioned].filter(id => !grounded.has(id));
+}
+/* 생성/조회 계열 도구 — 현재 인스턴스에 스코프되지 않음(instanceId 강제 주입 제외).
+ * proposeTwin 은 새 인스턴스를 만드는 것이라 주입하면 제안 id 가 덮어써진다. listTwinTypes 는 인스턴스 무관. */
+const UNSCOPED_TOOLS = new Set(['proposeTwin', 'listTwinTypes', 'suggestArchetype', 'refineTwin', 'listTwinSystems']);
+/** 신호(full attention 또는 trimmed signal)를 클라 entity360 가 읽는 attention 형태로 정규화.
+ *  full=recommendedActions[], trimmed=suggestedAction(단일) → recommendedActions[] 로 통일. */
+function anchorSignal(a) {
+    if (!a)
+        return undefined;
+    const acts = Array.isArray(a.recommendedActions) && a.recommendedActions.length
+        ? a.recommendedActions
+        : a.suggestedAction
+            ? [a.suggestedAction]
+            : [];
+    return { severity: a.severity, kind: a.kind, title: a.title, detail: a.detail, rationale: a.rationale, recommendedActions: acts };
+}
+/** 도구 결과에서 공간 앵커 수집(중복 제거). 두 경로 모두 커버: queryAttentions→out.attentions(full),
+ *  summarizeStatus→out.signals(trimmed). kind 는 클라 focus 표준으로(노드=location), 신호(원인·조치)를
+ *  attention 으로 함께 실어 공간 진입 시 재현되게 한다. attentions(full)가 signals(trimmed)를 덮도록 뒤에 둔다. */
+function collectAnchors(out, into) {
+    const list = [...(out?.signals ?? []), ...(out?.attentions ?? [])];
+    for (const a of list) {
+        const an = a?.anchor ?? {};
+        const sig = anchorSignal(a);
+        if (an.moverId)
+            into.set(`mover:${an.moverId}`, { kind: 'mover', id: an.moverId, attention: sig });
+        if (an.nodeId)
+            into.set(`location:${an.nodeId}`, { kind: 'location', id: an.nodeId, attention: sig });
+        if (an.orderId)
+            into.set(`order:${an.orderId}`, { kind: 'order', id: an.orderId, attention: sig });
+    }
+}
+/**
+ * 접지된 단발 질의 — 완주 후 반환. tool 루프는 단순(단일 read 도구, 최대 4 iteration).
+ * Gemini providerMeta(thoughtSignature) 는 tool_use turn 에 반드시 echo(안 하면 400).
+ */
+async function twinAiAsk(instanceId, message, domainId, history = [], locale) {
+    const client = (0, ai_client_base_1.getDefaultAIClient)();
+    if (!client?.chatWithTools) {
+        throw new Error('AI client (chatWithTools) not configured — check config.aiClient (provider/model/apiKey)');
+    }
+    // 로케일(프레임워크 제공값, 클라 i18next.language)이 오면 답변 언어를 명시 지시 — 메시지 언어에만
+    // 의존하지 않도록(짧거나 id 위주 질의·혼합 언어에도 안정). 구조화 라벨/카탈로그도 이 언어로 옮겨 말함.
+    const systemPrompt = locale
+        ? `${SYSTEM_PROMPT}\n- 사용자 로케일은 "${locale}" 이다. **답변과, 도구가 돌려준 영어 message·code·카탈로그 label 을 모두 이 언어로** 옮겨 전한다(메시지 언어와 무관).`
+        : SYSTEM_PROMPT;
+    // 대화 이력(클라 보관) 앞에 붙여 멀티턴 맥락 유지. 내부 tool_use/tool_result turn 은 넘기지 않고
+    // 사용자·어시스턴트 텍스트만 재현(필요하면 AI 가 도구를 다시 호출). 최근 12턴으로 제한(프롬프트 폭증 방지).
+    const priorTurns = (history ?? [])
+        .filter(h => h && typeof h.text === 'string' && h.text.trim())
+        .slice(-12)
+        .map(h => ({ role: h.role === 'ai' ? 'assistant' : 'user', content: h.text }));
+    const userTurn = `[instanceId=${instanceId}] ${message}`;
+    const messages = [...priorTurns, { role: 'user', content: userTurn }];
+    const used = [];
+    const anchors = new Map();
+    const proposals = [];
+    const provisions = [];
+    // 접지 근거 코퍼스 — LLM 이 실제로 받은 것: 사용자 입력 + 이력 텍스트 + 도구 출력(누적).
+    const grounded = [userTurn, ...priorTurns.map(t => (typeof t.content === 'string' ? t.content : ''))];
+    const finish = (reply) => ({
+        reply,
+        toolCalls: used,
+        anchors: [...anchors.values()],
+        proposedActions: proposals,
+        proposedProvisions: provisions,
+        groundingWarnings: checkGrounding(reply, grounded.join('\n'))
+    });
+    for (let i = 0; i < 4; i++) {
+        const res = await client.chatWithTools(messages, exports.TOOLS, { systemPrompt, maxTokens: 4096 });
+        if (!res.toolCalls?.length) {
+            return finish(res.text ?? '');
+        }
+        // assistant 의 tool_use turn + user 의 tool_result turn 을 누적(providerMeta echo 필수).
+        const assistantContent = [];
+        if (res.text)
+            assistantContent.push({ type: 'text', text: res.text });
+        for (const tc of res.toolCalls) {
+            assistantContent.push({ type: 'tool_use', id: tc.id, name: tc.name, arguments: tc.arguments, providerMeta: tc.providerMeta });
+        }
+        const toolResults = [];
+        for (const tc of res.toolCalls) {
+            used.push(tc.name);
+            if (tc.name === 'proposeAction') {
+                proposals.push({ command: tc.arguments.command, args: tc.arguments.args ?? {}, label: tc.arguments.label, reason: tc.arguments.reason });
+            }
+            // 생성/조회 계열은 현재 인스턴스에 스코프 안 함(proposeTwin=새 id). 그 외는 instanceId 강제(타 인스턴스 조회 방지).
+            const callArgs = UNSCOPED_TOOLS.has(tc.name) ? tc.arguments : { ...tc.arguments, instanceId };
+            const out = await execTool(tc.name, callArgs, domainId);
+            collectAnchors(out, anchors);
+            if ((tc.name === 'proposeTwin' || tc.name === 'refineTwin') && out?.draft) {
+                const o = out;
+                // viability·explanation 도 전달 — 클라 카드가 "작동 여부"·"평이한 구성"을 구조적으로 렌더(만만함, §12.6).
+                provisions.push({ ...o.draft, summary: o.summary, warnings: o.warnings, viability: o.viability, explanation: o.explanation });
+            }
+            const content = JSON.stringify(out);
+            grounded.push(content); // 도구 출력 = LLM 이 근거로 받는 사실(접지 가드 코퍼스)
+            toolResults.push({ type: 'tool_result', toolUseId: tc.id, content });
+        }
+        messages.push({ role: 'assistant', content: assistantContent });
+        messages.push({ role: 'user', content: toolResults });
+    }
+    return finish('(tool-iteration limit reached — please narrow the question and retry.)');
+}
+//# sourceMappingURL=assistant.js.map