@cartanova/qgrid-cli 2.5.1 → 2.5.3

package/bundle/src/application/qgrid/qgrid.frame.test.ts

@@ -1,3 +1,5 @@
+import { EventEmitter } from "node:events";
+
 import { Sonamu } from "sonamu";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
@@ -144,6 +146,10 @@ describe("QgridFrame.updateToken", () => {
 });
 
 describe("QgridFrame.query request logging", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
   beforeEach(() => {
     beforeQueryMock.mockReset().mockResolvedValue({ requestLogId: 41, stepIndex: 0 });
     afterQueryMock.mockReset().mockResolvedValue({});
@@ -237,6 +243,42 @@ describe("QgridFrame.query request logging", () => {
     expect(finishRunWithErrorMock).toHaveBeenCalledWith(41, "provider failed", args);
   });
 
+  it("aborts provider execution and marks the run aborted when the HTTP response closes early", async () => {
+    const requestRaw = Object.assign(new EventEmitter(), { aborted: false });
+    const responseRaw = Object.assign(new EventEmitter(), {
+      destroyed: false,
+      writableEnded: false,
+    });
+    vi.spyOn(Sonamu, "getContext").mockReturnValue({
+      transport: "http",
+      request: { raw: requestRaw },
+      reply: { raw: responseRaw },
+    } as never);
+    let providerSignal: AbortSignal | undefined;
+    dispatcherQueryMock.mockImplementationOnce(
+      (_args: unknown, signal: AbortSignal) =>
+        new Promise((_resolve, reject) => {
+          providerSignal = signal;
+          signal.addEventListener("abort", () => reject(new Error("provider aborted")), {
+            once: true,
+          });
+        }),
+    );
+    const args = { prompt: "hi", model: "anthropic/claude-opus-5" };
+
+    const queryPromise = QgridFrame.query(args);
+    await vi.waitFor(() => expect(providerSignal).toBeDefined());
+    responseRaw.destroyed = true;
+    responseRaw.emit("close");
+
+    await expect(queryPromise).rejects.toThrow("provider aborted");
+    expect(providerSignal?.aborted).toBe(true);
+    expect(finishRunAbortedMock).toHaveBeenCalledWith(41, args);
+    expect(finishRunWithErrorMock).not.toHaveBeenCalled();
+    expect(requestRaw.listenerCount("aborted")).toBe(0);
+    expect(responseRaw.listenerCount("close")).toBe(0);
+  });
+
   it("returns the provider result when afterQuery persistence fails", async () => {
     const output = queryOutput();
     dispatcherQueryMock.mockResolvedValueOnce(output);
@@ -266,6 +308,13 @@ describe("QgridFrame.query request logging", () => {
     expect(QueryInput.safeParse({ prompt: "hi", logMode: undefined }).success).toBe(false);
     expect(QueryInput.safeParse({ prompt: "hi", logger: false }).success).toBe(true);
   });
+
+  it("accepts bounded positive integer timeout values only", () => {
+    expect(QueryInput.safeParse({ prompt: "hi", timeout: 360_000 }).success).toBe(true);
+    expect(QueryInput.safeParse({ prompt: "hi", timeout: 0 }).success).toBe(false);
+    expect(QueryInput.safeParse({ prompt: "hi", timeout: 1.5 }).success).toBe(false);
+    expect(QueryInput.safeParse({ prompt: "hi", timeout: 1_800_001 }).success).toBe(false);
+  });
 });
 
 describe("QgridFrame.prepareStream", () => {

package/bundle/src/application/qgrid/qgrid.frame.ts

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 
 import { getLogger } from "@logtape/logtape";
-import { type FastifyReply } from "fastify";
+import { type FastifyReply, type FastifyRequest } from "fastify";
 import { api, BadRequestException, BaseFrameClass, Sonamu, stream } from "sonamu";
 import { getCacheManagerRef } from "sonamu/cache";
 
@@ -100,6 +100,43 @@ function rejectLegacyLogMode(args: QueryInput): void {
   );
 }
 
+function createHttpDisconnectHandle(): {
+  signal: AbortSignal;
+  dispose: () => void;
+} {
+  const abortController = new AbortController();
+  let requestRaw: FastifyRequest["raw"] | undefined;
+  let responseRaw: FastifyReply["raw"] | undefined;
+
+  try {
+    const ctx = Sonamu.getContext();
+    requestRaw = ctx.request?.raw;
+    if (ctx.transport === "http") responseRaw = ctx.reply.raw;
+  } catch {
+    // Direct frame calls (for example unit tests) do not have an HTTP context.
+  }
+
+  const abort = () => abortController.abort();
+  const abortOnIncompleteResponseClose = () => {
+    if (!responseRaw?.writableEnded) abort();
+  };
+
+  requestRaw?.once("aborted", abort);
+  responseRaw?.once("close", abortOnIncompleteResponseClose);
+
+  if (requestRaw?.aborted || (responseRaw?.destroyed && !responseRaw.writableEnded)) {
+    abort();
+  }
+
+  return {
+    signal: abortController.signal,
+    dispose: () => {
+      requestRaw?.removeListener("aborted", abort);
+      responseRaw?.removeListener("close", abortOnIncompleteResponseClose);
+    },
+  };
+}
+
 const logger = getLogger(["qgrid"]);
 const oauthLogger = getLogger(["qgrid", "oauth"]);
 
@@ -111,33 +148,49 @@ class QgridFrameClass extends BaseFrameClass {
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async query(args: QueryInput): Promise<QueryOutput> {
     rejectLegacyLogMode(args);
-    if (args.logger === false) {
-      return QgridDispatcher.query(args, args.timeout);
-    }
-
-    const { requestLogId, stepIndex } = await beforeQuery(args);
-    let result: QueryOutput;
+    const disconnect = createHttpDisconnectHandle();
     try {
-      result = await QgridDispatcher.query(args, args.timeout);
-    } catch (e) {
-      await finishRunWithError(requestLogId, (e as Error).message, args);
-      throw e;
-    }
+      if (args.logger === false) {
+        return await QgridDispatcher.query(args, disconnect.signal);
+      }
 
-    try {
-      const lifecycle = await afterQuery(requestLogId, stepIndex, args, result);
-      // tool-call requestLogId와 provider threadCoord는 서로 독립적으로 유지한다.
-      const threadCoord = result.runContext?.threadCoord;
-      const runContext =
-        lifecycle.runContext || threadCoord
-          ? { ...lifecycle.runContext, ...(threadCoord ? { threadCoord } : {}) }
-          : undefined;
-      return { ...result, runContext };
-    } catch (e) {
-      logger.error(`query afterQuery failed: ${(e as Error).message}`);
-      await finishRunWithError(requestLogId, (e as Error).message, args);
-      // provider 응답은 성공했으므로 로깅 장애가 생성 결과를 덮어쓰지 않는다.
-      return result;
+      const { requestLogId, stepIndex } = await beforeQuery(args);
+      let result: QueryOutput;
+      try {
+        result = await QgridDispatcher.query(args, disconnect.signal);
+      } catch (e) {
+        if (disconnect.signal.aborted) {
+          await finishRunAborted(requestLogId, args);
+        } else {
+          await finishRunWithError(requestLogId, (e as Error).message, args);
+        }
+        throw e;
+      }
+
+      try {
+        const lifecycle = await afterQuery(requestLogId, stepIndex, args, result);
+        if (disconnect.signal.aborted) {
+          await finishRunAborted(requestLogId, args);
+        }
+        // tool-call requestLogId와 provider threadCoord는 서로 독립적으로 유지한다.
+        const threadCoord = result.runContext?.threadCoord;
+        const runContext =
+          lifecycle.runContext || threadCoord
+            ? { ...lifecycle.runContext, ...(threadCoord ? { threadCoord } : {}) }
+            : undefined;
+        return { ...result, runContext };
+      } catch (e) {
+        logger.error(`query afterQuery failed: ${(e as Error).message}`);
+        if (disconnect.signal.aborted) {
+          await finishRunAborted(requestLogId, args);
+        } else {
+          await finishRunWithError(requestLogId, (e as Error).message, args);
+        }
+        // provider 응답은 성공했으므로 로깅 장애가 생성 결과를 덮어쓰지 않는다.
+        return result;
+      }
+    } finally {
+      disconnect.dispose();
     }
   }
 

package/bundle/src/application/qgrid/qgrid.types.ts

@@ -69,6 +69,9 @@ export const QgridInputPart = z.discriminatedUnion("type", [
 ]);
 export type QgridInputPart = z.infer<typeof QgridInputPart>;
 
+export const MAX_QUERY_TIMEOUT_MS = 30 * 60_000;
+export const QueryTimeoutMs = z.number().int().positive().max(MAX_QUERY_TIMEOUT_MS);
+
 // ─── Run Lifecycle Context (SDK ↔ Server contract) ───
 
 // codex thread 좌표. thread 재사용으로 conversation_id(=prompt_cache_key)를 고정해
@@ -103,7 +106,7 @@ export const QueryInput = z
     prompt: z.string(),
     input: z.array(QgridInputPart).optional(),
     model: z.string().optional(),
-    timeout: z.number().optional(),
+    timeout: QueryTimeoutMs.optional(),
     jsonSchema: z.string().optional(),
     tools: z.array(QgridTool).optional(),
     effort: z.string().optional(),

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

@@ -175,6 +175,18 @@ describe("AnthropicDispatcher", () => {
     expect(call.jsonSchema).toBe(JSON.stringify({ type: "object", properties: {} }));
   });
 
+  it("요청 timeoutMs를 Claude session에 전달하고 미지정 시 240초 기본값을 쓴다", async () => {
+    const d = new AnthropicDispatcher();
+    d.onTokenAdded(1, "tok-A", creds(), null, 1);
+
+    await d.generate(baseReq({ timeoutMs: 360_000 }));
+    expect(firstRunRequest().timeoutMs).toBe(360_000);
+
+    runClaudeSessionMock.mockClear();
+    await d.generate(baseReq());
+    expect(firstRunRequest().timeoutMs).toBe(240_000);
+  });
+
   it("quota 소진 → 에러", async () => {
     const d = new AnthropicDispatcher();
     d.onTokenAdded(1, "tok-A", creds(), null, 1);

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.ts

@@ -326,7 +326,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
           system: req.systemPrompt,
           jsonSchema,
           effort: req.effort,
-          timeoutMs: DEFAULT_TIMEOUT_MS,
+          timeoutMs: req.timeoutMs ?? DEFAULT_TIMEOUT_MS,
           coldHistory: req.coldHistory,
           input: req.coldInput,
           abortSignal: req.abortSignal,

package/bundle/src/utils/providers/anthropic/claude-session.test.ts

@@ -11,6 +11,7 @@ import {
   makeAnthropicWorkerId,
   oneMillionEnv,
   runClaudeSession,
+  shouldPinStructuredRetries,
   structuredOutputRetriesEnv,
   thinkingEnv,
   SYSTEM_PROMPT_ARGV_MAX_BYTES,
@@ -161,6 +162,24 @@ describe("buildClaudeArgs (멀티턴/격리/structured)", () => {
     expect(structuredOutputRetriesEnv("5")).toEqual({ MAX_STRUCTURED_OUTPUT_RETRIES: "5" });
   });
 
+  // SON-495 의 retry 고정 사유(스트림 retry = wall-clock 2배)는 스트리밍에만 성립한다.
+  // 논스트림 generate 까지 묶으면 1회 reject 가 곧 실패라 Claude 계열 structured 실패율이 치솟는다.
+  it("shouldPinStructuredRetries: structured + 스트리밍일 때만 retry 를 고정한다", () => {
+    expect(shouldPinStructuredRetries({ useStructured: true, includePartialMessages: true })).toBe(
+      true,
+    );
+    // 논스트림 structured: CC 기본 retry 허용
+    expect(shouldPinStructuredRetries({ useStructured: true, includePartialMessages: false })).toBe(
+      false,
+    );
+    expect(shouldPinStructuredRetries({ useStructured: true })).toBe(false);
+    // text 모드는 스트리밍 여부와 무관하게 영향 없음
+    expect(shouldPinStructuredRetries({ useStructured: false, includePartialMessages: true })).toBe(
+      false,
+    );
+    expect(shouldPinStructuredRetries({ useStructured: false })).toBe(false);
+  });
+
   it("cold-only: 항상 --session-id 를 사용하고 continuation flag 는 쓰지 않는다", () => {
     const args = buildClaudeArgs({ model: "m", sessionId: "uuid-1" });
     const continuationFlag = "--resume";

package/bundle/src/utils/providers/anthropic/claude-session.ts

@@ -171,6 +171,22 @@ export function structuredOutputRetriesEnv(raw = process.env.MAX_STRUCTURED_OUTP
   return { MAX_STRUCTURED_OUTPUT_RETRIES: String(Math.max(parsed, 1)) };
 }
 
+// SON-495 의 retry 고정은 "스트리밍 + structured" 조합 한정 정책이다. 스트림에서 retry 가 돌면
+// wall-clock 이 2배가 되어 실용성이 없기 때문이다(원 결정 사유). 논스트림 generate 는 애초에 완료를
+// 기다리므로 그 사유가 성립하지 않는다. 반면 Claude 계열은 OpenAI 대비 structured output 준수율이
+// 낮아, 논스트림까지 retry=1 로 묶으면 1회 reject 가 곧바로
+// `error_max_structured_output_retries` 로 직결된다(실측: deti_production opus-4-8 실패율 39.6%).
+// 스트리밍 여부는 `--include-partial-messages` 를 붙이는 generateStream 경로에서만 true 가 되므로
+// (anthropic-dispatcher 의 generate/generateStream 분기) 이를 실질 구분자로 쓴다.
+// 비성공 subtype 을 항상 isError 로 올리는 SON-495 의 나머지 절반은 그대로 유지된다 — retry 후에도
+// degenerate 출력이면 조용히 통과시키지 않고 정직하게 실패한다.
+export function shouldPinStructuredRetries(opts: {
+  useStructured: boolean;
+  includePartialMessages?: boolean;
+}): boolean {
+  return opts.useStructured && opts.includePartialMessages === true;
+}
+
 // Linux 단일 argv 인자 한계(MAX_ARG_STRLEN = PAGE_SIZE×32 = 128KB, 커널 하드코딩 상수)
 // 시스템 프롬프트가 이를 넘으면 execve 가 E2BIG 로 거부된다. deti 등 대형 프롬프트는 실측
 // 평균 343KB·최대 485KB(opus-4-8)라 일상적으로 초과한다. 한계의 절반(64KB)을 임계값으로 잡아
@@ -311,8 +327,14 @@ export function runClaudeSession(
           CLAUDE_CODE_DISABLE_BUNDLED_SKILLS: "1",
           CLAUDE_CODE_DISABLE_WORKFLOWS: "1",
           CLAUDE_CODE_ATTRIBUTION_HEADER: "0",
-          // structured output 일 때만 retry 를 고정한다(SON-495). text 모드는 영향 없음.
-          ...(useStructured ? structuredOutputRetriesEnv() : {}),
+          // structured + 스트리밍일 때만 retry 를 고정한다(SON-495). text 모드와 논스트림
+          // generate 는 CC 기본 retry 를 그대로 쓴다.
+          ...(shouldPinStructuredRetries({
+            useStructured,
+            includePartialMessages: req.includePartialMessages,
+          })
+            ? structuredOutputRetriesEnv()
+            : {}),
         },
       });
 

package/bundle/src/utils/providers/anthropic/stream-json-adapter.test.ts

@@ -265,6 +265,72 @@ describe("handleStreamJsonLine (출력 어댑터)", () => {
     expect(result!.costUsd).toBe(0.0042);
   });
 
+  it("structured retry 성공: 첫 거절 입력이 아니라 최종 structured_output을 반환", () => {
+    const rejected = {
+      l2: "en",
+      line_id: "s1_l1",
+      speaker: "Minjae",
+      title: "첫 시도",
+      scenes: [],
+    };
+    const accepted = {
+      title: "두 번째 시도",
+      opening_line: "스키마를 만족한 최종 응답",
+      scenes: [],
+    };
+    const { result } = runLines(
+      [
+        JSON.stringify({
+          type: "assistant",
+          message: {
+            content: [{ type: "tool_use", name: "StructuredOutput", input: rejected }],
+          },
+        }),
+        JSON.stringify({
+          type: "user",
+          message: {
+            content: [
+              {
+                type: "tool_result",
+                is_error: true,
+                content: "Output does not match required schema",
+              },
+            ],
+          },
+        }),
+        JSON.stringify({
+          type: "assistant",
+          message: {
+            content: [{ type: "tool_use", name: "StructuredOutput", input: accepted }],
+          },
+        }),
+        JSON.stringify({
+          type: "user",
+          message: {
+            content: [
+              {
+                type: "tool_result",
+                content: "Structured output provided successfully",
+              },
+            ],
+          },
+        }),
+        JSON.stringify({
+          type: "result",
+          subtype: "success",
+          is_error: false,
+          structured_output: accepted,
+          usage: { input_tokens: 10, output_tokens: 20 },
+        }),
+      ],
+      { structuredOutput: true },
+    );
+
+    expect(JSON.parse(result!.text)).toEqual(accepted);
+    expect(result!.isError).toBe(false);
+    expect(result!.subtype).toBe("success");
+  });
+
   // SON-495: error_max_structured_output_retries 는 모델이 schema 를 못 맞춘 비정상 종료다.
   // CC structured output 은 constrained decoding 이 아니라 사후 AJV 검증이라, 모델이 가끔
   // placeholder($PARAMETER_NAME)·거부("just kidding")·필드 누락 같은 발작/불완전 출력을 낸다.

package/bundle/src/utils/providers/anthropic/stream-json-adapter.ts

@@ -406,9 +406,20 @@ export function handleStreamJsonLine(
   }
 
   if (j.type === "result") {
+    const subtype = typeof j.subtype === "string" ? j.subtype : undefined;
+    const terminalReason = typeof j.terminal_reason === "string" ? j.terminal_reason : undefined;
+    const resultSucceeded =
+      j.is_error !== true &&
+      terminalReason !== "model_error" &&
+      (subtype === undefined || subtype === "success");
     let text: string;
     const preservedStructuredOutput = structuredOutput ? state?.structuredOutputText : undefined;
-    if (preservedStructuredOutput !== undefined) {
+    // Claude Code는 StructuredOutput 스키마 검증 실패 후 내부 재시도를 할 수 있다. assistant
+    // 이벤트의 첫 tool input은 거절된 시도일 수 있으므로, 성공 result가 제공한 최종 검증값을
+    // 우선한다. 첫 입력 보존값은 max_turns/retry 초과처럼 성공 result가 없는 진단 경로용이다.
+    if (structuredOutput && resultSucceeded && j.structured_output !== undefined) {
+      text = JSON.stringify(j.structured_output);
+    } else if (preservedStructuredOutput !== undefined) {
       text = preservedStructuredOutput;
     } else if (j.structured_output !== undefined) {
       text = JSON.stringify(j.structured_output);
@@ -429,8 +440,6 @@ export function handleStreamJsonLine(
     }
     const usage = toUsageBreakdown(rawUsage as ClaudeUsage);
     const quotaExhausted = text.startsWith("You've hit");
-    const subtype = typeof j.subtype === "string" ? j.subtype : undefined;
-    const terminalReason = typeof j.terminal_reason === "string" ? j.terminal_reason : undefined;
 
     // SON-495: 비정상 종료(error_max_structured_output_retries 등)는 정직하게 에러로 처리한다.
     // CC structured output 은 constrained decoding 이 아니라 "tool input 생성 후 사후 AJV 검증"이라

package/bundle/src/utils/providers/common/provider-dispatcher.ts

@@ -55,6 +55,8 @@ export interface GenerateRequest {
   verbosity?: string;
   reasoningSummary?: string;
   serviceTier?: string;
+  // provider 실행 제한(ms). 현재 Anthropic Claude session 타이머가 사용한다.
+  timeoutMs?: number;
   abortSignal?: AbortSignal;
   // 첫 turn / 재사용 폴백 시 보낼 input — 전체 prompt. 항상 설정.
   coldInput: Array<UserInput>;