@things-factory/figure-service 10.1.64 → 10.1.66

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

@@ -6,12 +6,12 @@
  * 하려면 어시스턴트가 **지금 무엇이 있는지 읽을 수 있어야** 한다. 읽지 못하면 매번 사람이 정본을
  * 붙여 넣어야 하고, 그러면 대화가 아니다.
  *
- * 능력을 복제하지 않는다. figure-service 가 이미 가진 진입점(`inspectSource` · `proposeFigure` ·
+ * 능력을 복제하지 않는다. figure-service 가 이미 가진 진입점(`inspectSource` · `proposeFigureV3` ·
  * 조회)을 레지스트리에 투영한다.
  *
  * ── 전부 조회·제안 전용이다 ─────────────────────────────────────────────────
  * 정본을 고치는 도구를 넣지 않는다. 형식의 설계가 그렇게 정해져 있다 — 어시스턴트는 **후보**를
- * 내고, 받을지 버릴지는 저작자가 정한다(`figure-propose.ts`). 되돌릴 수 없는 조작이 대화면으로
+ * 내고, 받을지 버릴지는 저작자가 정한다(`figure-propose-v3.ts`, ADR-0094). 되돌릴 수 없는 조작이 대화면으로
  * 새지 않으므로 전부 `kind: 'read'` 다.
  *
  * 저장은 저작면이 `updateFigure` 로 한다. 그 mutation 은 `figure:mutation` 이 지키고, 대화는
@@ -53,7 +53,7 @@ function getDeps(): any {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const format = require('./figure-format.js')
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const propose = require('./figure-propose.js')
+    const proposeV3 = require('./figure-propose-v3.js')
     _deps = {
       getRepository: shell.getRepository,
       Figure: entity.Figure,
@@ -65,7 +65,7 @@ function getDeps(): any {
       parseAnySource: format.parseAnySource,
       v3CostOf: model.v3CostOf,
       v3ScoreOf: model.v3ScoreOf,
-      proposeFigure: propose.proposeFigure,
+      proposeFigureV3: proposeV3.proposeFigureV3,
       compile: model.compile,
       costOf: model.costOf,
       scoreOf: model.scoreOf,
@@ -160,16 +160,15 @@ async function resolveFigureTarget(figureId: string | undefined, domainId: strin
 const isV3 = (source: any) => source?.version === 'figure-v3-asset-1'
 
 /**
- * The V2 proposer writes V2 figures; a V3 figure open in the modeller is not something it can revise or add to. Said as
- * what is true, with what the assistant can do instead -- not a V2 parser's complaint about a V3 asset (user,
- * 2026-09-24: the dock answered 「type 이 없다 · base 가 없다」 for a V3 draft).
+ * A revision is applied by the modeller on the version the model saw (ADR-0094), so only the figure open there can be
+ * revised. Said as what is true, with what the assistant can do instead.
  */
-function v3ProposalUnavailable() {
+function figureNotOpen() {
   return {
-    error: 'V3_PROPOSAL_UNAVAILABLE',
-    message: '이 도형은 V3 형식입니다. AI 후보 제안은 아직 V2 도형만 만들 수 있어 이 도형을 고치는 후보를 낼 수 없습니다.',
+    error: 'FIGURE_NOT_OPEN',
+    message: '고치는 제안은 모델러에 열려 있는 도형에만 낼 수 있습니다.',
     nextStep:
-      'Tell the person plainly that candidate proposals do not support V3 figures yet. You can still read the figure (getFigureSource) and explain whether it may be released and why (inspectFigure). Do not produce a V2 candidate for a V3 figure.'
+      'Tell the person to open the figure in the modeller and ask again there. A new figure needs no open one: call proposeFigureCandidate with create: true.'
   }
 }
 
@@ -221,23 +220,6 @@ function sourceForTool(row: any, host: any): { source: any; draft: boolean } {
   return { source: normalizedDraft, draft: true }
 }
 
-/**
- * 후보를 냈던 바로 그 Figure의 세션 반응만 후보 생성기에 넘긴다.
- *
- * 도크의 host context는 브라우저 값이므로 이 함수는 접근 권한을 판단하지 않는다. 이미 현재
- * 도메인에서 Figure를 찾은 뒤, `proposeFigure`가 다시 길이·형식을 정리할 참고 데이터만 건넨다.
- */
-function feedbackForTool(host: any, figureId?: string): unknown[] | undefined {
-  if (!Array.isArray(host?.proposalFeedback)) return undefined
-  if (figureId && host?.figureId === figureId) {
-    return host.proposalFeedback.slice(-5)
-  }
-  if (host?.editorMode === 'new' || !host?.figureId) {
-    return host.proposalFeedback.slice(-5)
-  }
-  return undefined
-}
-
 /**
  * 무엇을 고치라는 것인지 대화면 문맥에서 해소한다.
  *
@@ -395,9 +377,9 @@ function figureToolSpecs(): ToolSpec[] {
       /* 후보 생성 — 저장은 하지 않지만 같은 문의 권한을 쓴다. */
       doors: ['Mutation.proposeFigure'],
       description:
-        'Asks for a figure candidate from a description, optionally revising an existing one. ' +
-        'Returns the candidate with its score and cost. NOTHING IS SAVED — the author accepts or ' +
-        'discards it on screen. This is the only way a candidate reaches the screen.',
+        'Asks for a proposal: the modeller commands that make a new figure or revise the one open in the modeller. ' +
+        'Returns the commands with the score and cost of the figure they make. NOTHING IS SAVED — the author applies ' +
+        'the proposal in the modeller as one step, or leaves it. This is the only way a proposal reaches the screen.',
       schema: {
         type: 'object',
         properties: {
@@ -407,11 +389,11 @@ function figureToolSpecs(): ToolSpec[] {
           },
           figureId: {
             type: 'string',
-            description: 'Revise this figure. Omit to revise the one open in the editor; pass null to create anew.'
+            description: 'Revise this figure; it must be the one open in the modeller. Omit to revise the open one; pass null to create anew.'
           },
-          type: {
+          name: {
             type: 'string',
-            description: 'Type name for a new figure. Check listFigures first — it is a stored identifier.'
+            description: 'The name a person reads for a new figure.'
           },
           create: {
             type: 'boolean',
@@ -429,54 +411,52 @@ function figureToolSpecs(): ToolSpec[] {
           고치는 것인지 만드는 것인지를 **문맥에서 정한다.** 열린 도형이 있으면 고치는 것이 기본이고,
           모델이 `create` 를 켜면 만드는 것이다. 이것을 모델의 짐작에 맡기면 열려 있는 도형을 덮어쓰는
           후보가 온다.
+
+          고치는 제안은 모델러가 **요청 당시의 판(context · revision)** 위에 한 단계로 적용한다(ADR-0094).
+          그래서 고칠 수 있는 것은 모델러에 열린 도형뿐이고, 그 판을 문맥이 함께 실어 와야 한다.
         */
+        const host = ctx?.host
+        const create = args?.create === true || args?.figureId === null
         let base: unknown
-        if (!args?.create && args?.figureId !== null) {
-          const open = typeof args?.figureId === 'string' ? args.figureId : ctx?.host?.figureId
-          const row = await resolveFigureTarget(open ? open.trim() : undefined, domainId, ctx?.host)
-          if (row) {
-            base = sourceForTool(row, ctx?.host).source ?? undefined
+        let figureId: string | undefined
+        if (!create) {
+          const said = typeof args?.figureId === 'string' ? args.figureId.trim() : ''
+          const open = typeof host?.figureId === 'string' ? host.figureId.trim() : ''
+          if (said && said !== open) {
+            await figureInDomain(said, domainId)
+            return figureNotOpen()
           }
-        }
-        if (isV3(base) || (args?.create !== true && isV3(ctx?.host?.draftSource))) return v3ProposalUnavailable()
-
-        const palette = Array.isArray(ctx?.host?.palette) ? ctx.host.palette : []
-        if (palette.length === 0) {
-          /*
-            팔레트를 모르면 모델이 색을 지어내고, 그 후보는 그리는 시점에 `resolveToken` 이 던진다 —
-            저장까지 되고 나서 화면에서 죽는다. 빈 목록으로 진행하지 않는다.
-          */
-          throw new Error('the palette is missing from the host context — the candidate would invent colours')
+          if (!open) return missingFigureTarget()
+          const row = await resolveFigureTarget(open, domainId, host)
+          if (!row) return missingFigureTarget()
+          base = sourceForTool(row, host).source ?? undefined
+          if (!isV3(base)) return figureNotOpen()
+          if (typeof host?.context !== 'string' || !Number.isInteger(host?.revision)) return figureNotOpen()
+          figureId = open
         }
 
-        const { proposeFigure } = getDeps()
-        const feedback = feedbackForTool(ctx?.host, base ? figureIdFrom(args, ctx?.host) : undefined)
-
         let hostImage: { data: Buffer; mediaType: any } | undefined
-        const rawImage = ctx?.host?.image || (Array.isArray(ctx?.host?.attachments) ? ctx.host.attachments.find((a: any) => a?.mediaType?.startsWith('image/')) : undefined)
+        const rawImage = host?.image || (Array.isArray(host?.attachments) ? host.attachments.find((a: any) => a?.mediaType?.startsWith('image/')) : undefined)
         if (rawImage?.data) {
           const rawData = typeof rawImage.data === 'string' ? rawImage.data.replace(/^data:image\/[a-zA-Z]+;base64,/, '') : rawImage.data
           const buf = typeof rawData === 'string' ? Buffer.from(rawData, 'base64') : Buffer.from(rawData)
           hostImage = { data: buf, mediaType: rawImage.mediaType || 'image/png' }
         }
 
+        const { proposeFigureV3 } = getDeps()
         let result: any
         try {
-          result = await proposeFigure({
+          result = await proposeFigureV3({
             prompt,
-            palette,
             base,
-            type: typeof args?.type === 'string' ? args.type : undefined,
-            feedback,
-            refine: !!feedback?.length,
+            name: typeof args?.name === 'string' && args.name.trim() ? args.name.trim() : undefined,
             image: hostImage
           })
         } catch (error) {
           /*
-           * 후보 생성은 세 번의 JSON·형식 검사 끝에 실패할 수 있다. 그 마지막 검사 사유를
-           * ProposeFailure.reasons 에만 두면 agentic-loop은 "만들지 못했습니다"만 받아
-           * 사용자 화면에는 "응답이 비어있습니다"가 된다. 재시도할 수 있는 말로 경계를
-           * 넘긴다. 다른 예외(권한·통신)는 원문을 보존한다.
+           * 세 번 거절된 끝의 사유를 ProposeV3Failure.reasons 에만 두면 agentic-loop 은 「만들지 못했습니다」만
+           * 받아 화면에는 「응답이 비어있습니다」가 된다. 다시 시도할 수 있는 말로 경계를 넘긴다.
+           * 다른 예외(권한·통신)는 원문을 보존한다.
            */
           const reasons = Array.isArray((error as any)?.reasons) ? (error as any).reasons : []
           if (reasons.length > 0) throw new Error([(error as Error).message, ...reasons].join('\n'))
@@ -484,37 +464,26 @@ function figureToolSpecs(): ToolSpec[] {
         }
 
         /*
-          **`proposed: true` 가 카드를 만든다.** 이 표시가 없으면 후보는 도구 추적 안에 묻히고,
-          화면에는 아무것도 생기지 않는다 — 그러면 모델이 「후보를 만들었습니다」라고 쓴 것이
-          거짓말이 된다(사용자가 없는 단추를 찾는다).
-
-          `label`·`reason` 이 카드에 그려지는 두 줄이고, `args` 는 같은 제안을 두 번 세지 않기
-          위한 열쇠의 일부다 — 같은 요청을 두 번 내면 카드가 하나로 접힌다.
+          **`proposed: true` 가 카드를 만든다.** 이 표시가 없으면 제안은 도구 추적 안에 묻히고 화면에는
+          아무것도 생기지 않는다. 카드의 실행 단추가 figure-ui 의 처리기에 넘기고, 처리기가 모델러에 명령
+          목록을 한 단계로 적용한다. `args` 는 같은 제안을 두 번 세지 않기 위한 열쇠의 일부다.
         */
+        const name = result.source.name || 'Figure'
         return {
           proposed: true,
-          label: base ? `${result.source.type} 고치기` : `${result.source.type} 만들기`,
+          icon: 'view_in_ar',
+          label: create ? `${name} 만들기` : `${name} 고치기`,
           reason:
-            `등급 ${result.score.grade} · 삼각형 ${result.cost.triangles} · ` +
-            `한 도면 ${result.cost.at.drawCalls}회 · ${result.attempts}번에 만들었다`,
-          choices: [
-            { id: 'save', action: 'save', label: '초안 저장', icon: 'save', primary: true },
-            { id: 'repropose', action: 'prompt', label: '다른 콘셉트 재제안', icon: 'refresh', prompt: '현재 제안과 완전히 다른 스타일과 콘셉트로 새로 제안해줘' },
-            { id: 'slim', action: 'prompt', label: '비율 슬림 조정', icon: 'aspect_ratio', prompt: '전체적인 가로세로 비율을 좀 더 슬림하고 날렵하게 조정해줘' },
-            { id: 'palette', action: 'prompt', label: '색상 테마 변경', icon: 'palette', prompt: '다른 팔레트 색상 테마로 부품 색상을 변경해줘' },
-            { id: 'detail', action: 'prompt', label: '디테일 보강', icon: 'extension', prompt: '주요 디테일과 센서 부품을 좀 더 풍부하게 보강해줘' }
-          ],
-          args: {
-            baseSource: base ? JSON.stringify(base) : undefined,
-            prompt, figureId: base ? figureIdFrom(args, ctx?.host) : undefined,
-            draftType: base && ctx?.host?.editorMode === 'new' && !figureIdFrom(args, ctx?.host)
-              ? (base as any).type : undefined
-          },
-          source: result.source,
+            `명령 ${result.steps.length}개 · 등급 ${result.score?.grade ?? '-'} · 삼각형 ${result.cost.triangles} · ` +
+            `${result.attempts}번에 만들었다`,
+          args: { prompt, figureId, create },
+          create,
+          figureId,
+          context: create ? undefined : host.context,
+          revision: create ? undefined : host.revision,
+          steps: result.steps,
           score: result.score,
           cost: result.cost,
-          quality: result.quality,
-          violations: result.violations,
           attempts: result.attempts
         }
       }
@@ -537,13 +506,13 @@ export function registerFigureToolCategories(): void {
       '- **도형을 만들거나 고쳐 달라는 요청에는 반드시 `proposeFigureCandidate` 를 호출한다.**',
       '  후보는 도구 호출 결과에서만 생긴다.',
       '  호출 없이 "후보를 만들었습니다" · "적용 버튼을 누르세요" 라고 쓰는 것은 **거짓이다** — 화면에 후보 칸이 생기지 않으므로 사용자는 존재하지 않는 버튼을 찾는다.',
-      '  도크에서는 후보 카드의 버튼을 눌러야 모델러 비교 화면이 열린다. 아직 열지 않은 비교 화면이 이미 보인다고 말하지 않는다.',
-      '  요청한 부품만 바뀌었다고 추측하지 않는다. 후보와 원본을 비교한 근거가 없으면 변경 범위는 비교 화면에서 확인하도록 안내한다.',
+      '  후보는 모델러 명령 목록이다. 도크 카드의 실행 단추를 눌러야 모델러에 한 단계로 적용되고, 되돌리기 한 번에 통째로 돌아간다. 적용 전에 이미 바뀌었다고 말하지 않는다.',
+      '  고치는 제안은 모델러에 열린 도형에만 낼 수 있다. 결과의 `steps` 가 무엇을 하는지 그대로 전한다 — 명령에 없는 변경을 지어내지 않는다.',
       '- 정본을 직접 저장하지 않는다. 후보만 내고, 받을지 버릴지는 저작자가 화면에서 정한다.',
       '- 좌표와 크기는 X/Y/Z 축 이름으로 정확하게 표시한다. 확인되지 않은 가로·세로·높이 의미를 임의로 붙이지 않는다.',
       '- **고치라는 요청이면 먼저 `getFigureSource` 를 부른다.** 읽지 않고 고치면 짐작을 상대로 후보를 내게 되고, 부품 이름이 갈려 이미 배치된 보드의 바인딩이 끊긴다.',
-      '- 목록 화면에는 열린 도형이 없다. 기존 도형을 조회·수정할 때는 `listFigures`에서 사용자가 말한 이름·타입의 id를 찾는다. 대상이 모호할 때만 어느 도형인지 묻는다. 새 제작 요청에는 기존 정본을 조회하지 않고 `proposeFigureCandidate`를 create: true로 호출한다.',
-      '- 타입 이름을 지어내지 않는다 — `listFigures` 로 확인한다. **타입 이름은 저장되는 식별자**이고 보드가 그 이름으로 도형을 찾는다.',
+      '- 목록 화면에는 열린 도형이 없다. 기존 도형을 조회할 때는 `listFigures`에서 사용자가 말한 이름·타입의 id를 찾는다. 대상이 모호할 때만 어느 도형인지 묻는다. 기존 도형을 고치려면 모델러에서 그 도형을 열고 거기서 요청하도록 안내한다. 새 제작 요청에는 기존 정본을 조회하지 않고 `proposeFigureCandidate`를 create: true로 호출한다.',
+      '- 타입 이름을 지어내지 않는다 — `listFigures` 로 확인한다. **타입 이름은 저장되는 식별자**이고 보드가 그 이름으로 도형을 찾는다. 새 도형의 타입은 첫 저장 때 사람이 정한다.',
       '- 발행이 안 되는 이유를 물으면 `inspectFigure` 를 부른다. 판정 없이 "발행할 수 있습니다"라고 말하지 않는다.',
       '  판정의 각 항목은 **왜 문제인지와 무엇을 바꾸면 되는지**를 함께 담고 있다. 그대로 전한다 — 요약하면 저작자가 어느 부품의 어느 축을 고칠지 다시 찾아야 한다.',
       '- 무게·삼각형 수를 물으면 `getFigureSource` 의 `cost` 를 쓴다. 눈대중으로 세지 않는다.'

package/dist-server/service/figure/figure-propose.d.ts

@@ -1,91 +0,0 @@
-import { costOf, scoreOf } from '@hatiolab/figure-model';
-import type { FigureSource } from '@hatiolab/figure-model';
-import type { AIImageMediaType } from '@things-factory/ai-client-base';
-import type { FigureQualityReview } from './figure-quality.js';
-export interface ProposeInput {
-    /** 사람이 시킨 말. */
-    prompt: string;
-    /** 고쳐 달라는 것이면 지금 정본. 없으면 새로 만든다. */
-    base?: FigureSource;
-    /** 참고 그림. 설비 사진·렌더. */
-    image?: {
-        data: Buffer;
-        mediaType: AIImageMediaType;
-    };
-    /** 만들 타입 이름. 새로 만들 때 필요하다. */
-    type?: string;
-    /** 쓸 수 있는 팔레트 토큰. 여기 없는 토큰은 거절한다. */
-    palette: string[];
-    /** Measurable concerns warrant one more candidate attempt; never writes a Figure. */
-    refine?: boolean;
-    /** Explicit, session-only author reactions to earlier candidates; never persisted. */
-    feedback?: unknown;
-}
-/**
- * 후보 하나에 대한 저작자의 명시적 반응.
- *
- * 브라우저 문맥에서 온 참고 데이터다. 권한·저장·자동 변경의 근거가 될 수 없고, 다음 JSON 후보의
- * 방향을 잡는 데만 쓴다. 경계에서 다시 정규화해 프롬프트를 길게 하거나 명령을 주입하지 못하게 한다.
- */
-export interface ProposalFeedback {
-    outcome: 'accepted' | 'discarded';
-    selectedChanges: number;
-    totalChanges: number;
-    note?: string;
-    grade?: string;
-    quality?: {
-        status?: 'ready' | 'review';
-        findingCodes?: string[];
-    };
-}
-export interface ProposeResult {
-    source: FigureSource;
-    /** 재활용 점수와 한도 여유. */
-    score: ReturnType<typeof scoreOf>;
-    /** 무게. */
-    cost: ReturnType<typeof costOf>;
-    /** Explainable authoring review; JSON cannot certify visual aesthetics. */
-    quality: FigureQualityReview;
-    /** 형식은 맞으나 정책을 넘은 것. 막지 않고 알린다. */
-    violations: {
-        code: string;
-        message: string;
-    }[];
-    /** 몇 번 만에 됐나. 저작자에게 보여 줄 값은 아니지만 진단에 쓴다. */
-    attempts: number;
-}
-/** 못 만들었을 때. 조용히 빈 것을 돌려주지 않는다. */
-export declare class ProposeFailure extends Error {
-    /** 마지막 시도가 낸 사유들. 저작자에게 그대로 보여 준다. */
-    readonly reasons: string[];
-    readonly attempts: number;
-    constructor(message: string, 
-    /** 마지막 시도가 낸 사유들. 저작자에게 그대로 보여 준다. */
-    reasons: string[], attempts: number);
-}
-/**
- * 규칙을 프롬프트로 옮긴다.
- *
- * 값을 손으로 적지 않는다 — figure-model 의 상수에서 만든다. 그래야 한도가 바뀌면
- * 프롬프트도 같이 바뀐다.
- */
-export declare function rulesPrompt(palette: string[]): string;
-/**
- * 후보 하나를 받아 본다.
- *
- * 던지는 것이 아니라 **사유를 모아 돌려준다** — 사유가 다음 시도의 입력이 되기
- * 때문이다. 사람에게 보여 줄 것과 모델에 돌려줄 것이 같은 글이다.
- */
-export declare function inspect(parsed: unknown, palette: string[], expectedType?: string): {
-    source?: FigureSource;
-    reasons: string[];
-};
-/**
- * 말과 그림으로 후보를 만든다.
- *
- * 생성-검사 루프다. 도구 루프가 아니다 — 첫 조각에 도구는 필요 없다.
- *
- * 도구가 필요해지면 `@things-factory/ai-client-base` 의 `runAgenticLoop` 을 부른다.
- * 전에는 그것이 board-ai 안에만 있어 밖에서 쓸 수 없었는데, 공용으로 옮겨졌다.
- */
-export declare function proposeFigure(input: ProposeInput): Promise<ProposeResult>;