@cartanova/qgrid-cli 2.5.6 → 2.5.7

package/bundle/src/application/qgrid/tool-emulation.ts

@@ -22,34 +22,42 @@ const logger = getLogger(["qgrid", "tool-emulation"]);
 
 type EmulationResult = Omit<QueryOutput, "content" | "finishReason" | "runContext">;
 type ToolCall = { toolName: string; args: string };
-type LegacyToolCallResponse = {
-  action?: "answer" | "tool_call";
-  answer?: string | null;
-  toolCalls?: ToolCall[] | null;
-};
-
-const StructuredToolCallResponse = z.discriminatedUnion("action", [
-  z.strictObject({
-    action: z.literal("answer"),
-    answer: z.json().refine((answer) => answer !== null, {
-      message: "answer must be non-null",
-    }),
-    toolCalls: z.union([z.null(), z.tuple([])]),
-  }),
-  z.strictObject({
-    action: z.literal("tool_call"),
-    answer: z.null(),
-    toolCalls: z
-      .array(
-        z.strictObject({
-          toolName: z.string(),
-          args: z.string(),
-        }),
-      )
-      .min(1),
-  }),
-]);
-type StructuredResponse = z.infer<typeof StructuredToolCallResponse>;
+
+// envelope 는 {result: <union>} 한 겹 구조 — 스키마 근거는 tool-emulation-schema.ts 참조.
+// answer 타입만 요청 형태에 따라 다르다: tools-only 는 string(그대로 반환),
+// tools+jsonSchema 는 사용자 스키마의 JSON 값(JSON.stringify 로 반환).
+function buildEnvelopeSchema(answerKind: AnswerKind) {
+  return z.strictObject({
+    result: z.discriminatedUnion("action", [
+      z.strictObject({
+        action: z.literal("answer"),
+        answer:
+          answerKind === "text"
+            ? z.string()
+            : z.json().refine((answer) => answer !== null, {
+                message: "answer must be non-null",
+              }),
+        toolCalls: z.null(),
+      }),
+      z.strictObject({
+        action: z.literal("tool_call"),
+        answer: z.null(),
+        toolCalls: z
+          .array(
+            z.strictObject({
+              toolName: z.string(),
+              args: z.string(),
+            }),
+          )
+          .min(1),
+      }),
+    ]),
+  });
+}
+
+const TEXT_ENVELOPE = buildEnvelopeSchema("text");
+const JSON_ENVELOPE = buildEnvelopeSchema("json");
+type EnvelopeResponse = z.infer<typeof JSON_ENVELOPE>["result"];
 
 export class ToolCallEmulationError extends Error {
   constructor(message: string) {
@@ -64,70 +72,46 @@ interface EmulationImage {
   revisedPrompt?: string | null;
 }
 
+// answer 인코딩 종류. envelope 디코더는 한 벌이고 이 값은 answer 브랜치의 타입과
+// 최종 직렬화(text: 그대로 / json: JSON.stringify)만 가른다.
+export type AnswerKind = "text" | "json";
+
 interface ToolCallEmulationOptions {
   threadCoord?: QgridThreadCoord;
   images?: EmulationImage[];
-  answerMode?: "legacy" | "structured";
+  // 필수: 호출부가 answer 인코딩을 항상 명시해야 한다 (input.jsonSchema 유무로 판정).
+  answerKind: AnswerKind;
 }
 
 export function applyToolCallEmulation(
   result: EmulationResult,
-  tools?: QgridTool[],
-  options: ToolCallEmulationOptions = {},
+  tools: QgridTool[] | undefined,
+  options: ToolCallEmulationOptions,
 ): QueryOutput {
-  const { threadCoord, images, answerMode = "legacy" } = options;
+  const { threadCoord, images, answerKind } = options;
   const runContext = threadCoord ? { threadCoord } : undefined;
 
   if (!tools?.length) {
     return answerOutput(result, result.text, images, runContext);
   }
 
-  if (answerMode === "legacy") {
-    return applyLegacyResponse(result, tools, images, runContext);
-  }
-
-  const parsed = parseStructuredResponse(result.text, tools);
+  const parsed = parseEnvelope(result.text, tools, answerKind);
   if (parsed.action === "tool_call") {
     return toolCallOutput(result, parsed.toolCalls, images, runContext);
   }
 
-  return answerOutput(result, JSON.stringify(parsed.answer), images, runContext);
-}
-
-/**
- * Tools-only requests keep the permissive 2.5.3 contract. Structured-output requests use the
- * strict decoder below because their outer action envelope is an internal server contract.
- */
-function applyLegacyResponse(
-  result: EmulationResult,
-  tools: QgridTool[],
-  images: EmulationImage[] | undefined,
-  runContext: QueryOutput["runContext"],
-): QueryOutput {
-  let parsed: LegacyToolCallResponse;
-  try {
-    parsed = JSON.parse(result.text) as LegacyToolCallResponse;
-  } catch (error) {
-    logger.warn(
-      `tool-call emulation parse failed, falling back to text: ${(error as Error).message}`,
-    );
-    return answerOutput(result, result.text, images, runContext);
-  }
-
-  if (parsed.action === "tool_call") {
-    const toolCalls = parsed.toolCalls ?? [];
-    const unknownTool = findUnknownTool(toolCalls, tools);
-    if (unknownTool !== undefined) throw new Error(`unknown emulated tool: ${unknownTool}`);
-    return toolCallOutput(result, toolCalls, images, runContext);
-  }
-
-  return answerOutput(result, parsed.answer ?? result.text, images, runContext);
+  return answerOutput(
+    result,
+    answerKind === "text" ? (parsed.answer as string) : JSON.stringify(parsed.answer),
+    images,
+    runContext,
+  );
 }
 
-function parseStructuredResponse(text: string, tools: QgridTool[]) {
+function parseEnvelope(text: string, tools: QgridTool[], answerKind: AnswerKind) {
   if (Buffer.byteLength(text, "utf8") > STRUCTURED_ENVELOPE_LIMITS.maxUtf8Bytes) {
     throw new ToolCallEmulationError(
-      `structured-output envelope exceeds UTF-8 byte limit of ${STRUCTURED_ENVELOPE_LIMITS.maxUtf8Bytes}`,
+      `tool envelope exceeds UTF-8 byte limit of ${STRUCTURED_ENVELOPE_LIMITS.maxUtf8Bytes}`,
     );
   }
 
@@ -135,23 +119,27 @@ function parseStructuredResponse(text: string, tools: QgridTool[]) {
   try {
     value = JSON.parse(text);
   } catch (error) {
-    throw new ToolCallEmulationError(
-      `invalid structured-output envelope: ${(error as Error).message}`,
-    );
+    // 관용 폴백 없음: envelope 는 양 provider 의 structured output 으로 강제되는 내부
+    // 계약이라 여기 도달한 비 JSON 은 버그다. 과거의 텍스트 구제는 퇴화 봉투를 답변으로
+    // 흘려보내 조용한 오염을 만들었다(2026-07 medpath, 13.5k 건).
+    logger.warn(`tool envelope parse failed: ${(error as Error).message}`);
+    throw new ToolCallEmulationError(`invalid tool envelope: ${(error as Error).message}`);
   }
 
   assertStructuredEnvelopeComplexity(value);
-  const validation = StructuredToolCallResponse.safeParse(value);
+  const schema = answerKind === "text" ? TEXT_ENVELOPE : JSON_ENVELOPE;
+  const validation = schema.safeParse(value);
   if (!validation.success) {
     const issue = validation.error.issues[0];
     const path = issue && issue.path.length > 0 ? ` at ${issue.path.join(".")}` : "";
     const detail = issue?.message ?? "unknown validation issue";
-    throw new ToolCallEmulationError(`invalid structured-output envelope${path}: ${detail}`);
+    logger.warn(`tool envelope validation failed${path}: ${detail}`);
+    throw new ToolCallEmulationError(`invalid tool envelope${path}: ${detail}`);
   }
 
   // Zod clones JSON objects and drops own "__proto__" keys. The parsed JSON is safe to return
   // after validation and preserves the caller's exact structured value.
-  const response = value as StructuredResponse;
+  const response = (value as { result: EnvelopeResponse }).result;
   if (response.action === "tool_call") {
     const unknownTool = findUnknownTool(response.toolCalls, tools);
     if (unknownTool !== undefined) {

package/bundle/src/utils/providers/openai/codex-worker.test.ts

@@ -654,3 +654,150 @@ describe("CodexAppServerWorker image generation thread", () => {
     expect(params?.baseInstructions).toContain("Respond with text only");
   });
 });
+
+function unsubscribedIds(request: ReturnType<typeof vi.fn>): string[] {
+  return request.mock.calls
+    .filter(([method]) => method === "thread/unsubscribe")
+    .map(([, params]) => (params as { threadId: string }).threadId);
+}
+
+describe("CodexAppServerWorker thread unsubscribe on eviction", () => {
+  type ThreadMetaInternals = {
+    threadMeta: Map<string, { lastUsedAt: number }>;
+    rpc: { request: ReturnType<typeof vi.fn> };
+  };
+
+  function createWorkerWithUnsubscribeSpy() {
+    const worker = new CodexAppServerWorker({
+      tokenId: 1,
+      tokenName: "token",
+      accessToken: "access",
+      accountId: "account",
+    });
+    const request = vi.fn(async (_method: string, _params?: unknown) => ({}));
+    (worker as unknown as ThreadMetaInternals).rpc = { request };
+    return { worker, request, meta: (worker as unknown as ThreadMetaInternals).threadMeta };
+  }
+
+  it("sends thread/unsubscribe for TTL-expired threads", () => {
+    const { worker, request, meta } = createWorkerWithUnsubscribeSpy();
+    const now = Date.now();
+    meta.set("stale-1", { lastUsedAt: now - 11 * 60_000 });
+    meta.set("stale-2", { lastUsedAt: now - 20 * 60_000 });
+    meta.set("fresh", { lastUsedAt: now });
+
+    worker.sweepIdleThreads();
+
+    // 맵 제거(라우팅 차단)와 구독 해제가 함께 일어나야 codex 30분 언로드가 발동한다.
+    expect(meta.has("stale-1")).toBe(false);
+    expect(meta.has("stale-2")).toBe(false);
+    expect(meta.has("fresh")).toBe(true);
+    expect(unsubscribedIds(request).toSorted()).toEqual(["stale-1", "stale-2"]);
+  });
+
+  it("sends thread/unsubscribe for LRU-evicted threads over the cap", () => {
+    const { worker, request, meta } = createWorkerWithUnsubscribeSpy();
+    const now = Date.now();
+    for (let i = 0; i < 17; i++) {
+      meta.set(`t-${i}`, { lastUsedAt: now - (17 - i) * 1_000 });
+    }
+
+    worker.sweepIdleThreads();
+
+    // 상한(MAX-1=15)으로 줄이며 가장 오래된 2개가 축출·구독 해제된다.
+    expect(meta.size).toBe(15);
+    expect(unsubscribedIds(request).toSorted()).toEqual(["t-0", "t-1"]);
+  });
+
+  it("does not unsubscribe surviving threads", () => {
+    const { worker, request, meta } = createWorkerWithUnsubscribeSpy();
+    meta.set("live", { lastUsedAt: Date.now() });
+
+    worker.sweepIdleThreads();
+
+    expect(unsubscribedIds(request)).toEqual([]);
+  });
+});
+
+describe("CodexAppServerWorker image thread unsubscribe", () => {
+  const IMAGE_B64 = "iVBORw0KGgoBAgMEBQYHCA==";
+
+  it("unsubscribes the one-shot image thread right after a successful turn", async () => {
+    const { worker, request } = createWorkerWithNotificationRpc(
+      async (method, _params, handlers) => {
+        if (method === "thread/start") return { thread: { id: "t1" }, model: "gpt-test" };
+        if (method === "thread/unsubscribe") return {};
+        if (method === "turn/start") {
+          handlers.get("item/completed")?.({
+            threadId: "t1",
+            item: { type: "imageGeneration", id: "img-a", status: "generating", result: IMAGE_B64, revisedPrompt: null },
+          } as never);
+          handlers.get("turn/completed")?.({
+            threadId: "t1",
+            turn: { status: "completed", durationMs: 100 },
+          } as never);
+          return { turn: { id: "turn-1" } };
+        }
+        throw new Error(`unexpected request: ${method}`);
+      },
+    );
+
+    await worker.executeTurn({
+      input: [{ type: "text", text: "img", text_elements: [] }],
+      imageGeneration: true,
+    });
+
+    // 이미지 thread 는 threadMeta 미등록이라 sweep 이 못 잡는다 — turn 직후 즉시 구독 해제.
+    expect(unsubscribedIds(request)).toEqual(["t1"]);
+  });
+
+  it("unsubscribes the image thread even when the turn fails", async () => {
+    const { worker, request } = createWorkerWithNotificationRpc(
+      async (method, _params, handlers) => {
+        if (method === "thread/start") return { thread: { id: "t1" }, model: "gpt-test" };
+        if (method === "thread/unsubscribe") return {};
+        if (method === "turn/start") {
+          handlers.get("turn/completed")?.({
+            threadId: "t1",
+            turn: { status: "failed", durationMs: 100, error: { message: "boom" } },
+          } as never);
+          return { turn: { id: "turn-1" } };
+        }
+        throw new Error(`unexpected request: ${method}`);
+      },
+    );
+
+    await expect(
+      worker.executeTurn({
+        input: [{ type: "text", text: "img", text_elements: [] }],
+        imageGeneration: true,
+      }),
+    ).rejects.toThrow("turn failed");
+
+    // 실패해도 1 회용 thread 인 것은 같다 — base64 없이도 히스토리가 상주하므로 해제.
+    expect(unsubscribedIds(request)).toEqual(["t1"]);
+  });
+
+  it("keeps text threads subscribed so reuse turns still receive notifications", async () => {
+    const { worker, request } = createWorkerWithNotificationRpc(
+      async (method, _params, handlers) => {
+        if (method === "thread/start") return { thread: { id: "t1" }, model: "gpt-test" };
+        if (method === "turn/start") {
+          handlers.get("turn/completed")?.({
+            threadId: "t1",
+            turn: { status: "completed", durationMs: 100 },
+          } as never);
+          return { turn: { id: "turn-1" } };
+        }
+        throw new Error(`unexpected request: ${method}`);
+      },
+    );
+
+    await worker.executeTurn({
+      input: [{ type: "text", text: "hello", text_elements: [] }],
+    });
+
+    // 텍스트 thread 는 재사용 후보 — 구독을 유지해야 후속 turn 알림을 받는다.
+    expect(unsubscribedIds(request)).toEqual([]);
+  });
+});

package/bundle/src/utils/providers/openai/codex-worker.ts

@@ -506,13 +506,18 @@ export class CodexAppServerWorker {
     try {
       ttftTracker.markStart();
       await this.startTurnOnThread(threadId, req);
+      const result = await resultPromise;
+      return { ...result, threadId };
     } catch (e) {
       this.failActiveTurn(e as Error);
       await resultPromise.catch(() => {});
       throw e;
+    } finally {
+      // 이미지 thread 는 1 회용 cold thread 인데 threadMeta 에 등록되지 않아
+      // sweep 이 못 잡는다. MB 급 base64 가 상주하므로 turn 종료 즉시(성공/실패
+      // 불문) 구독을 끊어 codex 30분 언로드 대상으로 만든다.
+      if (req.imageGeneration) this.unsubscribeThread(threadId);
     }
-    const result = await resultPromise;
-    return { ...result, threadId };
   }
 
   async executeTurnStream(
@@ -556,12 +561,15 @@ export class CodexAppServerWorker {
   }
 
   // idle TTL 초과 / 개수 상한 초과 thread 를 정리. createThread 직전 lazy 호출.
-  // codex ephemeral thread 는 명시적 close RPC 없이 맵에서 제거 → 더 이상 turn 안 보냄.
+  // 맵 제거(재사용 라우팅 차단)와 함께 thread/unsubscribe 를 보낸다 — codex 는
+  // "구독자 0 + idle" 이 30분(THREAD_UNLOADING_DELAY, 하드코딩) 지속된 thread 를
+  // 메모리에서 자동 언로드하는데, thread/start 가 이 커넥션을 자동 구독자로 등록해
+  // 두기 때문에 unsubscribe 없이는 그 언로드가 영원히 발동하지 않는다(SON-516 실증).
   sweepIdleThreads(): void {
     const now = Date.now();
     for (const [id, meta] of this.threadMeta) {
       if (now - meta.lastUsedAt > CodexAppServerWorker.THREAD_IDLE_TTL_MS) {
-        this.threadMeta.delete(id);
+        this.evictThread(id);
       }
     }
     // createThread 직전 호출 → 새 thread 1 개가 곧 추가된다. 추가 후에도 MAX 를 넘지 않도록
@@ -572,10 +580,26 @@ export class CodexAppServerWorker {
         (a, b) => a[1].lastUsedAt - b[1].lastUsedAt,
       );
       const over = this.threadMeta.size - limit;
-      for (let i = 0; i < over; i++) this.threadMeta.delete(sorted[i]![0]);
+      for (let i = 0; i < over; i++) this.evictThread(sorted[i]![0]);
     }
   }
 
+  // thread 재사용 포기: 맵 제거(라우팅 차단)와 구독 해제를 한 단위로 묶는다.
+  // unsubscribe 한 thread 에 turn 을 보내면 알림이 이 커넥션으로 오지 않으므로
+  // 두 동작은 반드시 함께여야 한다.
+  private evictThread(threadId: string): void {
+    this.threadMeta.delete(threadId);
+    this.unsubscribeThread(threadId);
+  }
+
+  // 재사용을 포기한 thread 의 구독을 끊는다. 구독자가 없어진 idle thread 는 codex 가
+  // 30분 뒤 메모리에서 자동 언로드한다(SON-516 실증). fire-and-forget: 실패해도
+  // 무해(restart 시 프로세스째 회수). threadMeta 에 없는 이미지 1회용 thread 는
+  // evictThread 대신 이 메서드를 직접 호출한다.
+  private unsubscribeThread(threadId: string): void {
+    this.rpc?.request("thread/unsubscribe", { threadId }).catch(() => {});
+  }
+
   async interruptTurn(threadId: string, turnId: string): Promise<void> {
     if (!this.rpc || !this.ready) return;
     try {

package/bundle/src/utils/providers/openai/openai-dispatcher.test.ts

@@ -215,18 +215,19 @@ describe("OpenAIDispatcher worker capacity", () => {
     expect(makeOpenAIWorkerId(1, 10)).not.toBe(makeOpenAIWorkerId(2, 0));
   });
 
-  it("defaults to autoscaling from 5 to 15 workers per token", () => {
+  it("defaults to autoscaling from 1 to 3 workers per token", () => {
+    // dev0 OOM 사고(SON-516) 응급처치로 기본값을 5-15 에서 1-3 으로 축소 (f6d1333).
     expect(resolveOpenAIWorkerPoolConfig({})).toMatchObject({
       autoscale: true,
-      minWorkersPerToken: 5,
-      maxWorkersPerToken: 15,
+      minWorkersPerToken: 1,
+      maxWorkersPerToken: 3,
     });
   });
 
   it("keeps an explicit fixed worker mode for emergency rollback", () => {
     expect(
       resolveOpenAIWorkerPoolConfig({
-        QGRID_WORKERS_PER_TOKEN: "5",
+        QGRID_OPENAI_MIN_WORKERS_PER_TOKEN: "5",
         QGRID_OPENAI_AUTOSCALE: "false",
       }),
     ).toMatchObject({
@@ -236,6 +237,14 @@ describe("OpenAIDispatcher worker capacity", () => {
     });
   });
 
+  it("ignores the removed QGRID_WORKERS_PER_TOKEN variable", () => {
+    // 과거엔 min 의 폴백이었다 — dev0 사고 조사(SON-516)에서 이름과 달리 min 에만
+    // 꽂히는 함정으로 확인되어 제거. QGRID_OPENAI_MIN_WORKERS_PER_TOKEN 하나로 통일.
+    expect(
+      resolveOpenAIWorkerPoolConfig({ QGRID_WORKERS_PER_TOKEN: "15" }),
+    ).toMatchObject({ minWorkersPerToken: 1, maxWorkersPerToken: 3 });
+  });
+
   it("estimates worker RSS from the dev0 measurement model", () => {
     expect(estimateOpenAIWorkerRssGiB(50)).toBeCloseTo(8.56, 2);
     expect(estimateOpenAIWorkerRssGiB(60)).toBeCloseTo(10.13, 2);

package/bundle/src/utils/providers/openai/openai-worker-pool-config.ts

@@ -36,15 +36,9 @@ export function resolveOpenAIWorkerPoolConfig(
   env: Record<string, string | undefined> = process.env,
 ): OpenAIWorkerPoolConfig {
   const autoscale = env.QGRID_OPENAI_AUTOSCALE !== "false" && env.QGRID_OPENAI_AUTOSCALE !== "0";
-  const legacyWorkers = boundedInteger(
-    env.QGRID_WORKERS_PER_TOKEN,
-    DEFAULT_OPENAI_MIN_WORKERS_PER_TOKEN,
-    1,
-    MAX_OPENAI_WORKERS_PER_TOKEN,
-  );
   const minWorkersPerToken = boundedInteger(
     env.QGRID_OPENAI_MIN_WORKERS_PER_TOKEN,
-    legacyWorkers,
+    DEFAULT_OPENAI_MIN_WORKERS_PER_TOKEN,
     1,
     MAX_OPENAI_WORKERS_PER_TOKEN,
   );