@cartanova/qgrid-cli 2.1.1 → 2.2.1

package/bundle/src/utils/providers/common/model-cost.ts

@@ -14,16 +14,53 @@ export interface ModelCosts {
   inputTokens: number;
   outputTokens: number;
   cachedInputTokens: number;
+  /**
+   * long-context 할증. 전체 입력 토큰(input_tokens, cache_read 포함)이 threshold 초과 시
+   * 초과분만이 아니라 요청 전체(full session)에 배율 적용.
+   */
+  longContext?: {
+    threshold: number;
+    inputMultiplier: number;
+    cachedInputMultiplier: number;
+    outputMultiplier: number;
+  };
 }
 
 // ── OpenAI — codex app-server 에서 사용 가능한 모델 ─────────────────
+//
+// 가격 출처: https://openai.com/api/pricing (2026-06-11 확인)
+// 신모델 출시마다 단가가 바뀌므로(5.2→5.4→5.5) 모델 추가 시 반드시 공식 페이지 재확인해야함
+
+// GPT-5.4에서 처음 도입된 long-context 할증 (5.2/5.3-codex는 해당 없음, 5.4-mini는 미확인)
+// 272K 초과 시 input 2x / cached 2x / output 1.5x — 초과분만이 아닌 세션 전체에 적용됨
+// @see https://developers.openai.com/api/docs/models/gpt-5.5 ("prompts with >272K input tokens")
+const LONG_CONTEXT_272K: NonNullable<ModelCosts["longContext"]> = {
+  threshold: 272_000,
+  inputMultiplier: 2,
+  cachedInputMultiplier: 2,
+  outputMultiplier: 1.5,
+};
 
 const OPENAI_COSTS: Record<string, ModelCosts> = {
-  "gpt-5.5": { inputTokens: 2, outputTokens: 8, cachedInputTokens: 0.5 },
-  "gpt-5.4": { inputTokens: 2, outputTokens: 8, cachedInputTokens: 0.5 },
-  "gpt-5.4-mini": { inputTokens: 0.4, outputTokens: 1.6, cachedInputTokens: 0.1 },
-  "gpt-5.3-codex": { inputTokens: 2, outputTokens: 8, cachedInputTokens: 0.5 },
-  "gpt-5.2": { inputTokens: 2, outputTokens: 8, cachedInputTokens: 0.5 },
+  // https://openai.com/index/introducing-gpt-5-5/ (2026-04 출시)
+  "gpt-5.5": {
+    inputTokens: 5,
+    outputTokens: 30,
+    cachedInputTokens: 0.5,
+    longContext: LONG_CONTEXT_272K,
+  },
+  // https://openai.com/index/introducing-gpt-5-4/ (2026-03 출시)
+  "gpt-5.4": {
+    inputTokens: 2.5,
+    outputTokens: 15,
+    cachedInputTokens: 0.25,
+    longContext: LONG_CONTEXT_272K,
+  },
+  "gpt-5.4-mini": { inputTokens: 0.75, outputTokens: 4.5, cachedInputTokens: 0.075 },
+  // gpt-5.2와 동일 단가 (cached = input의 10%)
+  "gpt-5.3-codex": { inputTokens: 1.75, outputTokens: 14, cachedInputTokens: 0.175 },
+  // https://openai.com/index/introducing-gpt-5-2/ (cached input 90% 할인 명시)
+  "gpt-5.2": { inputTokens: 1.75, outputTokens: 14, cachedInputTokens: 0.175 },
 };
 
 // ── Anthropic ───────────────────────────────────────────────────────
@@ -57,10 +94,19 @@ export function calculateCostUsd(
   usage: { inputTokens: number; outputTokens: number; cachedInputTokens?: number },
 ): number {
   const costs = getModelCosts(model);
-  const nonCachedInput = usage.inputTokens - (usage.cachedInputTokens ?? 0);
+  const cachedInput = usage.cachedInputTokens ?? 0;
+  const nonCachedInput = usage.inputTokens - cachedInput;
+
+  // long-context 할증: 전체 입력(input_tokens, cache 포함)이 threshold 초과 시 요청 전체에 배율 적용
+  const lc = costs.longContext;
+  const isLongContext = lc !== undefined && usage.inputTokens > lc.threshold;
+  const inputRate = costs.inputTokens * (isLongContext ? lc.inputMultiplier : 1);
+  const cachedRate = costs.cachedInputTokens * (isLongContext ? lc.cachedInputMultiplier : 1);
+  const outputRate = costs.outputTokens * (isLongContext ? lc.outputMultiplier : 1);
+
   return (
-    (nonCachedInput / 1_000_000) * costs.inputTokens +
-    (usage.outputTokens / 1_000_000) * costs.outputTokens +
-    ((usage.cachedInputTokens ?? 0) / 1_000_000) * costs.cachedInputTokens
+    (nonCachedInput / 1_000_000) * inputRate +
+    (usage.outputTokens / 1_000_000) * outputRate +
+    (cachedInput / 1_000_000) * cachedRate
   );
 }

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

@@ -8,17 +8,32 @@ import { type JsonValue } from "../../../codex-protocol/serde_json/JsonValue";
 import { type TokenUsageBreakdown } from "../../../codex-protocol/v2/TokenUsageBreakdown";
 import { type UserInput } from "../../../codex-protocol/v2/UserInput";
 
+// thread 재사용 라우팅 좌표. 상위(qgrid.dispatcher)에서 conv 핸들 검증을 통과한 경우에만 전달.
+// dispatcher 는 이 좌표가 가리키는 worker 의 기존 thread 에 turn 만 실행한다.
+export interface ReuseThreadCoord {
+  workerId: number;
+  threadId: string;
+  epoch: number;
+}
+
 export interface GenerateRequest {
   model: string;
-  input: Array<UserInput>;
   systemPrompt?: string;
   outputSchema?: JsonValue;
   effort?: string;
   verbosity?: string;
   reasoningSummary?: string;
   serviceTier?: string;
-  history?: Array<JsonValue>;
   abortSignal?: AbortSignal;
+  // 첫 turn / 재사용 폴백 시 보낼 input — 전체 prompt. 항상 설정.
+  coldInput: Array<UserInput>;
+  // 첫 turn / 폴백 시 inject 할 전체 history.
+  coldHistory?: Array<JsonValue>;
+  // 재사용 좌표 + delta input. 둘은 한 쌍 — 검증 통과 시에만 설정한다.
+  // dispatcher 가 worker/thread 생존을 재검증해 성공하면 reuseInput(delta)을, 실패하면
+  // coldInput + coldHistory 로 폴백한다(전체 history 로 문맥 복구).
+  reuse?: ReuseThreadCoord;
+  reuseInput?: Array<UserInput>;
 }
 
 export interface GenerateResult {
@@ -27,6 +42,18 @@ export interface GenerateResult {
   usage: TokenUsageBreakdown;
   durationMs: number;
   model: string;
+  // 이번 turn 이 사용한 thread 좌표. 상위가 conv 핸들을 발급/갱신하는 데 쓴다.
+  threadCoord: ReuseThreadCoord;
+}
+
+// 상위(qgrid.dispatcher)로 가는 스트림 콜백. onComplete 는 non-stream 의 GenerateResult 와
+// 동일 shape(tokenName/threadCoord 포함)를 받아, 두 경로가 같은 일급 타입을 공유한다.
+export interface GenerateStreamCallbacks {
+  onDelta: (text: string) => void;
+  onComplete: (result: GenerateResult) => void;
+  onError: (error: Error) => void;
+  onThreadId?: (threadId: string) => void;
+  onTurnId?: (turnId: string) => void;
 }
 
 export interface ProviderDispatcher {

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

@@ -23,6 +23,36 @@ function createWorkerWithFakeRpc() {
   return { worker, handlers };
 }
 
+function createWorkerWithRequestSpy() {
+  const worker = new CodexAppServerWorker({
+    tokenId: 1,
+    tokenName: "token",
+    accessToken: "access",
+    accountId: "account",
+  });
+  const request = vi.fn(async (method: string, _params?: unknown) => {
+    if (method === "thread/start") {
+      return { thread: { id: "thread-1" }, model: "gpt-test" };
+    }
+    if (method === "turn/start") {
+      return { turn: { id: "turn-1" } };
+    }
+    throw new Error(`unexpected request: ${method}`);
+  });
+  (
+    worker as unknown as {
+      rpc: { request: typeof request };
+      ready: boolean;
+    }
+  ).rpc = { request };
+  (
+    worker as unknown as {
+      ready: boolean;
+    }
+  ).ready = true;
+  return { worker, request };
+}
+
 describe("CodexAppServerWorker active turn cleanup", () => {
   it("rejects a non-streaming turn when the worker process exits", async () => {
     const { worker } = createWorkerWithFakeRpc();
@@ -70,3 +100,64 @@ describe("CodexAppServerWorker active turn cleanup", () => {
     );
   });
 });
+
+describe("CodexAppServerWorker prompt prefix", () => {
+  it("uses the same base instructions with and without an output schema", async () => {
+    type WorkerInternals = {
+      createThread(req: unknown): Promise<{ threadId: string; model: string }>;
+      startTurnOnThread(threadId: string, req: unknown): Promise<{ turnId: string }>;
+    };
+
+    const textWorker = createWorkerWithRequestSpy();
+    {
+      const w = textWorker.worker as unknown as WorkerInternals;
+      const req = {
+        input: [{ type: "text", text: "hello", text_elements: [] }],
+        developerInstructions: "fixed system prompt",
+      };
+      const { threadId } = await w.createThread(req);
+      await w.startTurnOnThread(threadId, req);
+    }
+
+    const schemaWorker = createWorkerWithRequestSpy();
+    const outputSchema = {
+      type: "object",
+      additionalProperties: false,
+      properties: { answer: { type: "string" } },
+      required: ["answer"],
+    };
+    {
+      const w = schemaWorker.worker as unknown as WorkerInternals;
+      const req = {
+        input: [{ type: "text", text: "hello", text_elements: [] }],
+        developerInstructions: "fixed system prompt",
+        outputSchema,
+      };
+      const { threadId } = await w.createThread(req);
+      await w.startTurnOnThread(threadId, req);
+    }
+
+    const textThreadStart = textWorker.request.mock.calls.find(
+      ([method]) => method === "thread/start",
+    )?.[1] as { baseInstructions?: string; developerInstructions?: string } | undefined;
+    const schemaThreadStart = schemaWorker.request.mock.calls.find(
+      ([method]) => method === "thread/start",
+    )?.[1] as { baseInstructions?: string; developerInstructions?: string } | undefined;
+    expect(textThreadStart).toEqual(
+      expect.objectContaining({
+        baseInstructions: schemaThreadStart?.baseInstructions,
+        developerInstructions: "fixed system prompt",
+      }),
+    );
+    expect(schemaThreadStart).toEqual(
+      expect.objectContaining({
+        developerInstructions: "fixed system prompt",
+      }),
+    );
+
+    const schemaTurnStart = schemaWorker.request.mock.calls.find(
+      ([method]) => method === "turn/start",
+    )?.[1];
+    expect(schemaTurnStart).toEqual(expect.objectContaining({ outputSchema }));
+  });
+});

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

@@ -66,10 +66,8 @@ const THREAD_DEFAULTS = {
   },
 } satisfies Partial<ThreadStartParams>;
 
-const BASE_INSTRUCTIONS = {
-  text: "You are a helpful assistant. Do not use any tools such as shell, file operations, or web search. Respond with text only.",
-  withSchema: "You are a helpful assistant. Respond using the provided output schema.",
-} as const;
+const BASE_INSTRUCTIONS =
+  "You are a helpful assistant. Do not use any tools such as shell, file operations, or web search. Respond with text only.";
 
 // codex가 매 요청에 자동 주입하는 내장 tool(shell/web_search/spawn_agent 등 14개)과
 // instruction 블록(permissions/environment_context/skills, ~10KB)을 비활성화
@@ -112,6 +110,14 @@ export class CodexAppServerWorker {
   // restart 시 rpc 객체가 새로 생성되므로, 핸들러를 보관했다가 매 spawn마다 재바인딩한다.
   serverRequestHandler?: (method: string, params: unknown) => Promise<unknown>;
 
+  // thread 재사용(prompt cache): worker 가 생성한 thread 들의 메타.
+  // ephemeral thread 는 이 프로세스 메모리에만 존재하므로 restart 시 전부 무효.
+  private threadMeta = new Map<string, { lastUsedAt: number }>();
+  // spawn 카운터. restart 마다 증가 → conv 핸들의 epoch 와 대조해 stale thread 감지.
+  private epochCounter = 0;
+  private static readonly THREAD_IDLE_TTL_MS = 10 * 60_000;
+  private static readonly MAX_THREADS_PER_WORKER = 16;
+
   constructor(private config: WorkerConfig) {
     const suffix = config.workerIndex !== undefined ? `-${config.workerIndex}` : "";
     this.codexHome = `/tmp/qgrid-codex/${config.tokenId}${suffix}`;
@@ -120,6 +126,9 @@ export class CodexAppServerWorker {
   // ── Lifecycle ───────────────────────────────────────────────────
 
   private async spawnAndInit(): Promise<void> {
+    // 새 codex 프로세스 → 기존 ephemeral thread 전부 무효. epoch 증가로 stale 감지.
+    this.epochCounter++;
+    this.threadMeta.clear();
     const cwd = `${this.codexHome}/cwd`;
     mkdirSync(cwd, { recursive: true });
     // codex 내장 tool/web_search/instruction 블록 비활성화
@@ -254,6 +263,9 @@ export class CodexAppServerWorker {
   get tokenId(): number {
     return this.config.tokenId;
   }
+  get workerIndex(): number {
+    return this.config.workerIndex ?? 0;
+  }
   get tokenName(): string {
     return this.config.tokenName;
   }
@@ -313,10 +325,12 @@ export class CodexAppServerWorker {
     return !this.busy;
   }
 
-  async startThread(
-    req: TurnRequest,
-  ): Promise<{ threadId: string; turnId: string; model: string }> {
+  // 새 thread 생성 (thread/start + 필요 시 history inject). 첫 turn / 폴백 경로용.
+  // 후속 turn 은 createThread 없이 startTurnOnThread 만 호출해 conversation_id 를 고정한다.
+  // thread 의 기본 model 도 반환 (req.model 미지정 시 fallback).
+  async createThread(req: TurnRequest): Promise<{ threadId: string; model: string }> {
     if (!this.rpc || !this.ready) throw new Error("worker not ready");
+    this.sweepIdleThreads();
 
     const threadConfig: ThreadStartParams["config"] = {
       ...THREAD_DEFAULTS.config,
@@ -327,7 +341,7 @@ export class CodexAppServerWorker {
       {
         ephemeral: true,
         cwd: `${this.codexHome}/cwd`,
-        baseInstructions: req.outputSchema ? BASE_INSTRUCTIONS.withSchema : BASE_INSTRUCTIONS.text,
+        baseInstructions: BASE_INSTRUCTIONS,
         developerInstructions: req.developerInstructions ?? "",
         sandbox: THREAD_DEFAULTS.sandbox,
         approvalPolicy: THREAD_DEFAULTS.approvalPolicy,
@@ -336,13 +350,20 @@ export class CodexAppServerWorker {
     );
 
     const threadId = thread.id;
-    const model = req.model ?? threadModel;
     if (req.history?.length) {
       await this.rpc.request("thread/inject_items", {
         threadId,
         items: req.history,
       } satisfies ThreadInjectItemsParams);
     }
+    this.threadMeta.set(threadId, { lastUsedAt: Date.now() });
+
+    return { threadId, model: req.model ?? threadModel };
+  }
+
+  // 기존 thread 에 turn 만 실행 (inject 없음). conversation_id 유지 → prompt cache 적중.
+  private async startTurnOnThread(threadId: string, req: TurnRequest): Promise<{ turnId: string }> {
+    if (!this.rpc || !this.ready) throw new Error("worker not ready");
 
     const { turn } = await this.rpc.request<TurnStartResponse>("turn/start", {
       threadId,
@@ -353,20 +374,79 @@ export class CodexAppServerWorker {
       ...(req.reasoningSummary ? { summary: req.reasoningSummary } : {}),
       ...(req.serviceTier ? { serviceTier: req.serviceTier } : {}),
     });
-
-    return { threadId, turnId: turn.id, model };
+    const meta = this.threadMeta.get(threadId);
+    if (meta) meta.lastUsedAt = Date.now();
+    return { turnId: turn.id };
   }
 
-  async executeTurn(req: TurnRequest): Promise<TurnResult> {
-    const { threadId, model } = await this.startThread(req);
-    return this.consumeTurnNotifications(threadId, model);
+  // existingThreadId 있으면 그 thread 재사용(후속 turn), 없으면 새 thread 생성(첫 turn).
+  // 호출 후 사용한 threadId 를 반환해 dispatcher 가 conv 핸들을 발급한다.
+  async executeTurn(
+    req: TurnRequest,
+    existingThreadId?: string,
+  ): Promise<TurnResult & { threadId: string }> {
+    let threadId: string;
+    let model: string;
+    if (existingThreadId) {
+      threadId = existingThreadId;
+      model = req.model ?? "";
+    } else {
+      ({ threadId, model } = await this.createThread(req));
+    }
+    await this.startTurnOnThread(threadId, req);
+    const result = await this.consumeTurnNotifications(threadId, model);
+    return { ...result, threadId };
   }
 
-  async executeTurnStream(req: TurnRequest, cb: StreamCallbacks): Promise<void> {
-    const { threadId, turnId, model } = await this.startThread(req);
+  async executeTurnStream(
+    req: TurnRequest,
+    cb: StreamCallbacks,
+    existingThreadId?: string,
+  ): Promise<{ threadId: string }> {
+    let threadId: string;
+    let model: string;
+    if (existingThreadId) {
+      threadId = existingThreadId;
+      model = req.model ?? "";
+    } else {
+      ({ threadId, model } = await this.createThread(req));
+    }
+    const { turnId } = await this.startTurnOnThread(threadId, req);
     cb.onThreadId?.(threadId);
     cb.onTurnId?.(turnId);
-    return this.consumeStreamNotifications(threadId, model, cb);
+    await this.consumeStreamNotifications(threadId, model, cb);
+    return { threadId };
+  }
+
+  // ── thread 재사용 지원 ───────────────────────────────────────────
+
+  get epoch(): number {
+    return this.epochCounter;
+  }
+
+  hasThread(threadId: string): boolean {
+    return this.threadMeta.has(threadId);
+  }
+
+  // idle TTL 초과 / 개수 상한 초과 thread 를 정리. createThread 직전 lazy 호출.
+  // codex ephemeral thread 는 명시적 close RPC 없이 맵에서 제거 → 더 이상 turn 안 보냄.
+  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);
+      }
+    }
+    // createThread 직전 호출 → 새 thread 1 개가 곧 추가된다. 추가 후에도 MAX 를 넘지 않도록
+    // MAX-1 이하로 줄여 둔다(그래야 생성 직후 정확히 MAX). LRU: lastUsedAt 오름차순으로 제거.
+    const limit = CodexAppServerWorker.MAX_THREADS_PER_WORKER - 1;
+    if (this.threadMeta.size > limit) {
+      const sorted = [...this.threadMeta.entries()].toSorted(
+        (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]);
+    }
   }
 
   async interruptTurn(threadId: string, turnId: string): Promise<void> {
@@ -438,7 +518,10 @@ export class CodexAppServerWorker {
 
       this.rpc!.onNotification("thread/tokenUsage/updated", (p) => {
         if (p.threadId !== threadId) return;
-        usage = p.tokenUsage.total;
+        // thread 재사용 시 .total 은 대화 전체 누적이라, cold 였던 이전 turn 까지 섞여
+        // 이 요청 자체의 cache 적중률이 희석된다(예: turn1 cold 0% + turn2 90% → 48% 로 기록).
+        // .last 는 이번 turn 만의 usage 라 request_log 가 그 요청의 실제 토큰을 정확히 반영한다.
+        usage = p.tokenUsage.last;
       });
 
       this.rpc!.onNotification("turn/completed", (p) => {
@@ -524,7 +607,10 @@ export class CodexAppServerWorker {
 
       this.rpc!.onNotification("thread/tokenUsage/updated", (p) => {
         if (p.threadId !== threadId) return;
-        usage = p.tokenUsage.total;
+        // thread 재사용 시 .total 은 대화 전체 누적이라, cold 였던 이전 turn 까지 섞여
+        // 이 요청 자체의 cache 적중률이 희석된다(예: turn1 cold 0% + turn2 90% → 48% 로 기록).
+        // .last 는 이번 turn 만의 usage 라 request_log 가 그 요청의 실제 토큰을 정확히 반영한다.
+        usage = p.tokenUsage.last;
       });
 
       this.rpc!.onNotification("turn/completed", (p) => {

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

@@ -13,14 +13,10 @@ import { type OpenAICredentials } from "../../../application/token/token.types";
 import {
   type GenerateRequest,
   type GenerateResult,
+  type GenerateStreamCallbacks,
   type ProviderDispatcher,
 } from "../common/provider-dispatcher";
-import {
-  CodexAppServerWorker,
-  type StreamCallbacks,
-  type TurnRequest,
-  type TurnResult,
-} from "./codex-worker";
+import { CodexAppServerWorker, type StreamCallbacks, type TurnRequest } from "./codex-worker";
 import { handleChatgptAuthTokensRefresh } from "./openai-refresh";
 
 const logger = getLogger(["qgrid", "openai-dispatcher"]);
@@ -35,6 +31,17 @@ const QUEUE_TIMEOUT_MS = 60_000;
 const MAX_QUEUE_SIZE = 50;
 const SPAWN_INTERVAL_MS = 500;
 
+// thread 재사용(prompt cache 고정). 끄면 기존 "매 turn 새 thread + history inject" 동작.
+const THREAD_REUSE_ENABLED = process.env.QGRID_OPENAI_THREAD_REUSE !== "false";
+// 좌표 worker 가 busy 일 때 free 를 기다리는 최대 시간. 초과 시 새 thread 로 폴백.
+const REUSE_WORKER_WAIT_MS = 5_000;
+const REUSE_WORKER_POLL_MS = 50;
+
+// workerId 합성: tokenId 와 workerIndex(0..4) 를 하나의 안정 숫자로 인코딩.
+function makeWorkerId(tokenId: number, workerIndex: number): number {
+  return tokenId * 10 + workerIndex;
+}
+
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -130,6 +137,17 @@ export class OpenAIDispatcher implements ProviderDispatcher {
   // ── Generate ────────────────────────────────────────────────────
 
   async generate(req: GenerateRequest): Promise<GenerateResult> {
+    // thread 재사용 경로: 좌표 worker 를 점유해 기존 thread 에 turn 만 실행.
+    const reuseWorker = await this.acquireReuseWorker(req);
+    if (reuseWorker) {
+      logger.info(
+        `↻ ${reuseWorker.tokenName}[${reuseWorker.tokenId}] (reuse thread, ${req.model})`,
+      );
+      return this.executeAndRelease(reuseWorker, (w) =>
+        this.executeTurn(w, req, req.reuse!.threadId),
+      );
+    }
+
     const worker = this.acquireIdleWorker();
     if (worker) {
       logger.info(`→ ${worker.tokenName}[${worker.tokenId}] (model: ${req.model})`);
@@ -141,7 +159,15 @@ export class OpenAIDispatcher implements ProviderDispatcher {
     });
   }
 
-  async generateStream(req: GenerateRequest, cb: StreamCallbacks): Promise<void> {
+  async generateStream(req: GenerateRequest, cb: GenerateStreamCallbacks): Promise<void> {
+    const reuseWorker = await this.acquireReuseWorker(req);
+    if (reuseWorker) {
+      logger.info(`↻ ${reuseWorker.tokenName}[${reuseWorker.tokenId}] (reuse thread, [stream])`);
+      return this.executeAndRelease(reuseWorker, (w) =>
+        this.executeStreamTurn(w, req, cb, req.reuse!.threadId),
+      );
+    }
+
     const worker = this.acquireIdleWorker();
     if (worker) {
       logger.info(`→ ${worker.tokenName}[${worker.tokenId}] (model: ${req.model}, [stream])`);
@@ -153,6 +179,37 @@ export class OpenAIDispatcher implements ProviderDispatcher {
     });
   }
 
+  // reuse 좌표가 유효하면 그 worker 를 busy 점유해 반환. 없거나 폴백 대상이면 null.
+  // 폴백 사유: 기능 off / 좌표 없음 / worker 부재·죽음 / epoch 불일치(restart) / thread 소멸 /
+  //            busy 대기 타임아웃. null 반환 시 호출부는 새 thread 경로로 진행.
+  async acquireReuseWorker(req: GenerateRequest): Promise<CodexAppServerWorker | null> {
+    if (!THREAD_REUSE_ENABLED || !req.reuse) return null;
+    const { workerId, threadId, epoch } = req.reuse;
+
+    const worker = this.findWorkerById(workerId);
+    if (!worker || !worker.isReady || !worker.active) return null;
+    if (worker.epoch !== epoch) return null;
+    if (!worker.hasThread(threadId)) return null;
+
+    const deadline = Date.now() + REUSE_WORKER_WAIT_MS;
+    for (;;) {
+      // restart(epoch 변경) / thread 소멸이 대기 중에 발생하면 폴백.
+      if (worker.epoch !== epoch || !worker.hasThread(threadId)) return null;
+      if (worker.tryAcquireTurn()) return worker;
+      if (Date.now() >= deadline) return null;
+      await sleep(REUSE_WORKER_POLL_MS);
+    }
+  }
+
+  findWorkerById(workerId: number): CodexAppServerWorker | null {
+    for (const workers of this.workerPool.values()) {
+      for (const w of workers) {
+        if (makeWorkerId(w.tokenId, w.workerIndex) === workerId) return w;
+      }
+    }
+    return null;
+  }
+
   async interruptWorkerTurn(threadId: string, turnId: string): Promise<void> {
     const allWorkers = [...this.workerPool.values()].flat().filter((w) => w.isReady);
     await Promise.allSettled(allWorkers.map((w) => w.interruptTurn(threadId, turnId)));
@@ -264,53 +321,73 @@ export class OpenAIDispatcher implements ProviderDispatcher {
     }
   }
 
-  async executeTurn(worker: CodexAppServerWorker, req: GenerateRequest): Promise<GenerateResult> {
-    const turnReq: TurnRequest = {
-      input: req.input,
+  // reuseThreadId 가 있으면 기존 thread 에 delta(reuseInput)만, 없으면 새 thread 에 전체
+  // prompt(coldInput) + history inject. reuse 가 dispatcher 단에서 폴백되면 후자로 떨어진다.
+  private buildTurnRequest(req: GenerateRequest, reuseThreadId?: string): TurnRequest {
+    const reusing = reuseThreadId !== undefined;
+    return {
+      input: reusing && req.reuseInput ? req.reuseInput : req.coldInput,
+      history: reusing ? undefined : req.coldHistory,
       developerInstructions: req.systemPrompt,
       outputSchema: req.outputSchema,
       effort: req.effort ?? DEFAULT_EFFORT,
       model: req.model,
-      history: req.history,
       verbosity: req.verbosity,
       reasoningSummary: req.reasoningSummary,
       serviceTier: req.serviceTier,
     };
-    const result: TurnResult = await worker.executeTurn(turnReq);
+  }
+
+  async executeTurn(
+    worker: CodexAppServerWorker,
+    req: GenerateRequest,
+    reuseThreadId?: string,
+  ): Promise<GenerateResult> {
+    const turnReq = this.buildTurnRequest(req, reuseThreadId);
+    const result = await worker.executeTurn(turnReq, reuseThreadId);
     return {
       text: result.text,
       tokenName: worker.tokenName,
       usage: result.usage,
       durationMs: result.durationMs,
       model: result.model,
+      threadCoord: {
+        workerId: makeWorkerId(worker.tokenId, worker.workerIndex),
+        threadId: result.threadId,
+        epoch: worker.epoch,
+      },
     };
   }
 
   async executeStreamTurn(
     worker: CodexAppServerWorker,
     req: GenerateRequest,
-    cb: StreamCallbacks,
+    cb: GenerateStreamCallbacks,
+    reuseThreadId?: string,
   ): Promise<void> {
-    const turnReq: TurnRequest = {
-      input: req.input,
-      developerInstructions: req.systemPrompt,
-      outputSchema: req.outputSchema,
-      effort: req.effort ?? DEFAULT_EFFORT,
-      model: req.model,
-      history: req.history,
-      verbosity: req.verbosity,
-      reasoningSummary: req.reasoningSummary,
-      serviceTier: req.serviceTier,
-    };
+    const turnReq = this.buildTurnRequest(req, reuseThreadId);
+    // worker 의 TurnResult 에 tokenName/threadCoord 를 붙여 상위(GenerateResult)로 올린다.
+    // threadId 는 새 thread 면 onThreadId 로 확정되므로 미리 보관해 두고 onComplete 때 읽는다.
+    let resolvedThreadId = reuseThreadId ?? "";
     const wrappedCb: StreamCallbacks = {
       ...cb,
+      onThreadId: (threadId) => {
+        resolvedThreadId = threadId;
+        cb.onThreadId?.(threadId);
+      },
       onComplete: (result) => {
-        cb.onComplete({ ...result, tokenName: worker.tokenName } as TurnResult & {
-          tokenName: string;
+        cb.onComplete({
+          ...result,
+          tokenName: worker.tokenName,
+          threadCoord: {
+            workerId: makeWorkerId(worker.tokenId, worker.workerIndex),
+            threadId: resolvedThreadId,
+            epoch: worker.epoch,
+          },
         });
       },
     };
-    await worker.executeTurnStream(turnReq, wrappedCb);
+    await worker.executeTurnStream(turnReq, wrappedCb, reuseThreadId);
   }
 
   // ── Spawn ───────────────────────────────────────────────────────

package/bundle/web-dist/client/assets/cost-CpjVoAqp.js

@@ -0,0 +1 @@
+var e=1e6,t=4;function n(t){return t/e}function r(e){return`$${e.toFixed(t)}`}function i(e){return r(n(e))}function a(e){return e.input_tokens<=0?`—`:`${Math.round(e.cache_read_tokens/e.input_tokens*100)}%`}export{i as n,r,a as t};