@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/backends/codex_auth.js

@@ -11,9 +11,10 @@ import { randomBytes } from 'crypto';
 import { chmodSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
-import { buildResponsesInput, isValidResponsesTerminal, parseResponsesOutput, readBoundedResponsesText, requireValidResponsesOutputItem, streamResponsesSSE, } from './openai_responses.js';
+import { buildResponsesInput, isValidResponsesTerminal, parseResponsesOutput, readBoundedResponsesText, readBoundedProviderError, requireValidResponsesOutputItem, streamResponsesSSE, } from './openai_responses.js';
 import { RateLimitError, parseResetAt } from './rate_limit.js';
 import { CODEX_LEGACY_PROVIDER } from './provider_ids.js';
+import { CodexBufferedRecovery } from './codex_buffered_recovery.js';
 /**
  * Shared auth file with Codex CLI (~/.codex/auth.json). Both ZTC and Codex CLI
  * read and write this file. ZTC replaces it atomically, so concurrent readers
@@ -33,6 +34,8 @@ function resolveClientId(fileClientId) {
     return process.env.CODEX_OAUTH_CLIENT_ID || fileClientId || DEFAULT_CODEX_CLIENT_ID;
 }
 const CODEX_OAUTH_TIMEOUT_MS = 30_000;
+// Credential refresh is small control-plane JSON, not an inference response.
+const CODEX_OAUTH_RESPONSE_BYTES = 1_048_576;
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
@@ -209,7 +212,7 @@ export class CodexAuthManager {
         }
         let rawData;
         try {
-            const body = await readBoundedResponsesText(res);
+            const body = await readBoundedResponsesText(res, CODEX_OAUTH_RESPONSE_BYTES);
             rawData = JSON.parse(body);
         }
         catch (error) {
@@ -321,7 +324,7 @@ export class CodexAuthBackend {
         return headers;
     }
     /** POST the streaming Responses request, refreshing the token once on 401. */
-    async fetchResponses(request, _retried = false) {
+    async fetchResponses(request, _retried = false, recovery) {
         const headers = await this.buildHeaders(request.signal);
         const input = buildResponsesInput(request.messages);
         const tools = request.tools.map(t => ({
@@ -330,9 +333,10 @@ export class CodexAuthBackend {
             description: t.description,
             parameters: t.parameters,
         }));
+        const system = request.system || 'You are a helpful assistant.';
         const body = {
             model: request.model,
-            instructions: request.system || 'You are a helpful assistant.',
+            instructions: request.outputTokenGuidance ? `${system}\nAim for at most ${request.maxTokens} output tokens.` : system,
             input,
             stream: true,
             store: false,
@@ -344,6 +348,11 @@ export class CodexAuthBackend {
             body.tools = tools;
             body.tool_choice = 'auto';
         }
+        if (request.outputSchema !== undefined) {
+            body.text = { format: {
+                    type: 'json_schema', name: 'ztc_response', strict: request.outputSchemaStrict ?? false, schema: request.outputSchema,
+                } };
+        }
         // Codex/GPT reasoning effort + fast mode (Responses API shape). Always
         // request a reasoning summary so the agent's thinking streams to the UI as a
         // collapsed thinking block (gpt-5.x are reasoning models).
@@ -353,18 +362,20 @@ export class CodexAuthBackend {
         if (request.codexFastMode) {
             body.service_tier = 'priority';
         }
-        const response = await fetch(`${CODEX_API_BASE}/responses`, {
+        const response = await (recovery?.fetch ?? fetch)(`${CODEX_API_BASE}/responses`, {
             method: 'POST',
             headers,
             body: JSON.stringify(body),
             signal: request.signal,
         });
         if (!response.ok) {
-            if (response.status === 401 && !_retried) {
+            if (response.status === 401 && !_retried && (!recovery || recovery.canPost())) {
+                if (recovery)
+                    await response.body?.cancel();
                 await this.authManager.refreshToken(request.signal);
-                return this.fetchResponses(request, true);
+                return this.fetchResponses(request, true, recovery);
             }
-            const errorText = await readBoundedResponsesText(response);
+            const errorText = await readBoundedProviderError(response);
             if (response.status === 429) {
                 // Typed so the rotation engine can cool this account and fail over.
                 const now = Date.now();
@@ -384,12 +395,55 @@ export class CodexAuthBackend {
             }
             throw new Error(`Codex API error (${response.status}): ${errorText}`);
         }
-        return response;
+        return request.maxResponseBytes === undefined ? response : this.boundResponse(response, request.maxResponseBytes);
+    }
+    boundResponse(response, maxBytes) {
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+            void response.body?.cancel();
+            throw new Error('Codex response byte budget must be a positive integer');
+        }
+        if (!response.body)
+            return response;
+        const reader = response.body.getReader();
+        let received = 0;
+        const body = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        controller.close();
+                        reader.releaseLock();
+                        return;
+                    }
+                    received += value.byteLength;
+                    if (received > maxBytes) {
+                        const error = new Error('Codex response byte budget exceeded');
+                        controller.error(error);
+                        await reader.cancel(error);
+                        reader.releaseLock();
+                        return;
+                    }
+                    controller.enqueue(value);
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+            async cancel(reason) {
+                await reader.cancel(reason);
+                reader.releaseLock();
+            },
+        }, { highWaterMark: 0 });
+        return new Response(body, { status: response.status, headers: response.headers });
     }
     /** Buffered path — kept as the fallback when streaming can't run. */
     async generate(request) {
+        if (request.bufferedRecovery) {
+            const recovery = new CodexBufferedRecovery(request.bufferedRecovery, request.signal);
+            return recovery.run(async () => this.parseSSEResponse(await this.fetchResponses(request, false, recovery), request.maxResponseBytes));
+        }
         const response = await this.fetchResponses(request);
-        return this.parseSSEResponse(response);
+        return this.parseSSEResponse(response, request.maxResponseBytes);
     }
     /**
      * Real incremental streaming over the Responses API SSE. Delegates to the
@@ -398,15 +452,15 @@ export class CodexAuthBackend {
      * tool_use + usage + stopReason assembled from the completed output items.
      */
     async *generateStream(request) {
-        yield* streamResponsesSSE(await this.fetchResponses(request));
+        yield* streamResponsesSSE(await this.fetchResponses(request), request.maxResponseBytes);
     }
     /**
      * Parse SSE stream and build a BackendResponse.
      * The ChatGPT backend streams output items via response.output_item.done
      * events, while response.completed carries usage but has output: [].
      */
-    async parseSSEResponse(response) {
-        const text = await readBoundedResponsesText(response);
+    async parseSSEResponse(response, maxBytes) {
+        const text = await readBoundedResponsesText(response, maxBytes);
         const outputItems = [];
         let usage;
         let terminalStatus;

package/dist/agent/backends/codex_buffered_recovery.d.ts

@@ -0,0 +1,27 @@
+import type { BufferedRecoveryRequest } from './types.js';
+export declare class CodexBufferedDeadlineError extends Error {
+    constructor();
+}
+/** Pull-through transport only. The caller retains its existing SSE/output parser. */
+export declare class CodexBufferedRecovery {
+    private readonly policy;
+    private readonly parent?;
+    private readonly controller;
+    private readonly deadlineTimer;
+    private readonly onParentAbort;
+    private readonly epochAtStart;
+    private readonly monotonicAtStart;
+    private readonly interrupted;
+    private readonly duration;
+    private posts;
+    private body;
+    private last;
+    constructor(policy: BufferedRecoveryRequest, parent?: AbortSignal | undefined);
+    /** Epoch-shaped stamps share one monotonic clock across both physical attempts. */
+    private now;
+    canPost(): boolean;
+    private emit;
+    private canRecover;
+    run<T>(complete: () => Promise<T>): Promise<T>;
+    readonly fetch: (url: string, init: RequestInit) => Promise<Response>;
+}

package/dist/agent/backends/codex_buffered_recovery.js

@@ -0,0 +1,293 @@
+import { createHash } from 'node:crypto';
+export class CodexBufferedDeadlineError extends Error {
+    constructor() { super('Buffered Codex absolute deadline exceeded'); this.name = 'CodexBufferedDeadlineError'; }
+}
+/** Pull-through transport only. The caller retains its existing SSE/output parser. */
+export class CodexBufferedRecovery {
+    policy;
+    parent;
+    controller = new AbortController();
+    deadlineTimer;
+    onParentAbort;
+    epochAtStart = Date.now();
+    monotonicAtStart = performance.now();
+    interrupted;
+    duration;
+    posts = 0;
+    body;
+    last;
+    constructor(policy, parent) {
+        this.policy = policy;
+        this.parent = parent;
+        this.interrupted = policy.version === 'codex-buffered-idle-overload-interrupted-v1' || policy.version === 'codex-buffered-idle-overload-duration-interrupted-v1';
+        this.duration = policy.version === 'codex-buffered-idle-overload-duration-v1' || policy.version === 'codex-buffered-idle-overload-duration-interrupted-v1';
+        if (!['codex-buffered-idle-v1', 'codex-buffered-idle-overload-v1', 'codex-buffered-idle-overload-duration-v1', 'codex-buffered-idle-overload-interrupted-v1', 'codex-buffered-idle-overload-duration-interrupted-v1'].includes(policy.version) || policy.idleTimeoutMs !== 8000
+            || (this.duration && (!('firstBodyTimeoutMs' in policy) || policy.firstBodyTimeoutMs !== 30000))
+            || !Number.isFinite(policy.deadlineAtMs))
+            throw new Error('Unsupported buffered Codex recovery policy');
+        this.onParentAbort = () => this.controller.abort(parent?.reason);
+        if (parent?.aborted)
+            this.onParentAbort();
+        else
+            parent?.addEventListener('abort', this.onParentAbort, { once: true });
+        this.deadlineTimer = setTimeout(() => this.controller.abort(new CodexBufferedDeadlineError()), Math.max(0, policy.deadlineAtMs - this.now()));
+    }
+    /** Epoch-shaped stamps share one monotonic clock across both physical attempts. */
+    now() {
+        return this.epochAtStart + (performance.now() - this.monotonicAtStart);
+    }
+    canPost() {
+        return this.posts < 2 && !this.controller.signal.aborted && this.now() < this.policy.deadlineAtMs;
+    }
+    emit(event) {
+        try {
+            this.policy.onAttempt?.({ ...event });
+        }
+        catch { /* Missing metadata invalidates capture, not gameplay. */ }
+    }
+    canRecover() {
+        const event = this.last?.event;
+        return event?.reason === 'idle' || (this.duration && event?.reason === 'body-duration')
+            || (this.interrupted && event?.reason === 'body-interrupted')
+            || (this.policy.version !== 'codex-buffered-idle-v1'
+                && event?.reason === 'complete' && event.status === 200 && event.eofAtMs !== undefined
+                && event.providerFailure === 'provider-overload');
+    }
+    async run(complete) {
+        try {
+            while (true) {
+                this.controller.signal.throwIfAborted();
+                try {
+                    return await complete();
+                }
+                catch (error) {
+                    if (!this.canRecover() || !this.canPost())
+                        throw error;
+                    // Cancellation must finish before the next POST. The same absolute abort still wins.
+                    await new Promise((resolve, reject) => {
+                        const abort = () => reject(this.controller.signal.reason);
+                        this.controller.signal.addEventListener('abort', abort, { once: true });
+                        void this.last.settled.then(resolve, reject).finally(() => this.controller.signal.removeEventListener('abort', abort));
+                        if (this.controller.signal.aborted)
+                            abort();
+                    });
+                    this.controller.signal.throwIfAborted();
+                    if (!this.canRecover() || !this.canPost())
+                        throw error;
+                }
+            }
+        }
+        finally {
+            clearTimeout(this.deadlineTimer);
+            this.parent?.removeEventListener('abort', this.onParentAbort);
+        }
+    }
+    fetch = async (url, init) => {
+        this.controller.signal.throwIfAborted();
+        if (!this.canPost())
+            throw new Error('Buffered Codex POST budget exhausted');
+        this.body ??= String(init.body);
+        const attemptController = new AbortController();
+        const signal = AbortSignal.any([this.controller.signal, attemptController.signal]);
+        const event = {
+            trigger: this.posts === 0 ? 'initial' : this.last?.event.reason === 'idle' ? 'body-idle' : this.last?.event.reason === 'body-duration' ? 'body-duration' : this.last?.event.reason === 'body-interrupted' ? 'body-interrupted' : this.last?.event.providerFailure === 'provider-overload' ? 'provider-overload' : 'auth-refresh',
+            timingClock: 'monotonic-epoch-v1', type: 'started', attempt: ++this.posts, bodySha256: createHash('sha256').update(this.body).digest('hex'),
+            bodyBytes: Buffer.byteLength(this.body), startedAtMs: this.now(), deadlineAtMs: this.policy.deadlineAtMs, bytes: 0, chunks: 0, usage: 'unknown',
+        };
+        let settle;
+        const settled = new Promise(resolve => { settle = resolve; });
+        this.last = { event, settled };
+        this.emit(event);
+        let finished = false;
+        let idleTimer;
+        let bodyTimer;
+        let removeAbort = () => { };
+        const finish = (reason) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(idleTimer);
+            clearTimeout(bodyTimer);
+            removeAbort();
+            event.type = 'settled';
+            event.reason = reason;
+            event.endedAtMs = this.now();
+            this.emit(event);
+            settle();
+        };
+        let response;
+        try {
+            response = await fetch(url, { ...init, body: this.body, signal });
+            event.status = response.status;
+            event.headersAtMs = this.now();
+        }
+        catch (error) {
+            if (signal.aborted)
+                event.abortAtMs = this.now();
+            finish(signal.aborted ? 'abort' : 'transport-error');
+            throw error;
+        }
+        if (!response.body) {
+            event.eofAtMs = this.now();
+            finish(response.ok ? 'complete' : 'http-error');
+            return response;
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let lines = '';
+        let retryAllowed = true;
+        let overload = false;
+        let stopping = false;
+        let pending;
+        let output;
+        const stop = async (reason, error) => {
+            if (stopping || finished)
+                return settled;
+            stopping = true;
+            clearTimeout(idleTimer);
+            clearTimeout(bodyTimer);
+            event.reason = reason;
+            event.cancelledAtMs = this.now();
+            const cancellation = reader.cancel(error);
+            event.abortAtMs = this.now();
+            attemptController.abort(error);
+            if (reason !== 'consumer-cancel')
+                output.error(error);
+            try {
+                await cancellation;
+                await pending?.catch(() => { });
+            }
+            catch (failure) {
+                event.reason = 'transport-error';
+                throw failure;
+            }
+            finally {
+                reader.releaseLock();
+                finish(response.ok ? event.reason : 'http-error');
+            }
+        };
+        const armCutoff = (reason, observedAtMs, timeoutMs) => {
+            const check = () => {
+                if (finished || stopping || !retryAllowed || this.posts !== 1)
+                    return;
+                const remaining = observedAtMs + timeoutMs - this.now();
+                if (remaining > 0) {
+                    const timer = setTimeout(check, Math.ceil(remaining));
+                    if (reason === 'idle')
+                        idleTimer = timer;
+                    else
+                        bodyTimer = timer;
+                    return;
+                }
+                void stop(reason, new Error(reason === 'idle' ? 'Buffered Codex body idle cutoff' : 'Buffered Codex first body duration cutoff')).catch(() => { });
+            };
+            const timer = setTimeout(check, timeoutMs);
+            if (reason === 'idle')
+                idleTimer = timer;
+            else
+                bodyTimer = timer;
+        };
+        const observeLine = (line) => {
+            if (!line.startsWith('data:'))
+                return;
+            const data = line.slice(5).trim();
+            let type;
+            let message;
+            try {
+                const parsed = data === '[DONE]' ? { type: '[DONE]' } : JSON.parse(data);
+                type = parsed.type;
+                message = (parsed.response?.error ?? parsed.error)?.message;
+            }
+            catch {
+                retryAllowed = false;
+                overload = false;
+                clearTimeout(bodyTimer);
+            }
+            if (type && ['response.completed', 'response.incomplete', 'response.failed', 'error', '[DONE]'].includes(type)) {
+                overload = this.policy.version !== 'codex-buffered-idle-v1' && retryAllowed
+                    && type === 'response.failed' && message === 'Our servers are currently overloaded. Please try again later.';
+                if (!this.interrupted || event.semanticTerminal === undefined) {
+                    event.semanticTerminal = type;
+                    event.semanticTerminalAtMs = this.now();
+                }
+                retryAllowed = false;
+                clearTimeout(bodyTimer);
+            }
+        };
+        const observe = (chunk) => {
+            event.bytes += chunk.byteLength;
+            event.chunks += 1;
+            event.lastChunkAtMs = this.now();
+            if (this.duration && response.status === 200
+                && chunk.byteLength > 0 && event.firstChunkAtMs === undefined) {
+                event.firstChunkAtMs = event.lastChunkAtMs;
+                if (retryAllowed && this.posts === 1)
+                    armCutoff('body-duration', event.firstChunkAtMs, 30000);
+            }
+            lines += decoder.decode(chunk, { stream: true });
+            let end;
+            while ((end = lines.indexOf('\n')) !== -1) {
+                const line = lines.slice(0, end).trim();
+                lines = lines.slice(end + 1);
+                observeLine(line);
+            }
+            clearTimeout(idleTimer);
+            if (response.status === 200 && retryAllowed && this.posts === 1) {
+                armCutoff('idle', event.lastChunkAtMs, this.policy.idleTimeoutMs);
+            }
+        };
+        const now = () => this.now();
+        const interruptionPolicy = this.interrupted;
+        const overloadPolicy = this.policy.version !== 'codex-buffered-idle-v1';
+        const stream = new ReadableStream({
+            start(controller) {
+                output = controller;
+                const abort = () => { void stop('abort', signal.reason).catch(() => { }); };
+                signal.addEventListener('abort', abort, { once: true });
+                removeAbort = () => signal.removeEventListener('abort', abort);
+                if (signal.aborted)
+                    abort();
+            },
+            async pull(controller) {
+                try {
+                    pending = reader.read();
+                    const { done, value } = await pending;
+                    if (stopping)
+                        return;
+                    if (done) {
+                        if (overloadPolicy) {
+                            observeLine((lines + decoder.decode()).trim());
+                            if (overload && response.status === 200)
+                                event.providerFailure = 'provider-overload';
+                        }
+                        event.eofAtMs = now();
+                        reader.releaseLock();
+                        finish(response.ok ? 'complete' : 'http-error');
+                        if (interruptionPolicy && response.ok && event.semanticTerminal !== 'response.completed') {
+                            controller.error(new Error('Buffered Codex body ended without a completed response'));
+                        }
+                        else
+                            controller.close();
+                    }
+                    else {
+                        observe(value);
+                        controller.enqueue(value);
+                    }
+                }
+                catch (error) {
+                    if (stopping)
+                        return;
+                    // A terminal event without a newline must still prohibit replacing its output.
+                    if (interruptionPolicy)
+                        observeLine((lines + decoder.decode()).trim());
+                    const interrupted = interruptionPolicy && !signal.aborted && response.status === 200 && event.bytes > 0 && retryAllowed;
+                    reader.releaseLock();
+                    finish(signal.aborted ? 'abort' : interrupted ? 'body-interrupted' : 'transport-error');
+                    controller.error(error);
+                }
+            },
+            cancel: reason => stop('consumer-cancel', reason),
+        }, { highWaterMark: 0 });
+        return new Response(stream, { status: response.status, headers: response.headers });
+    };
+}

package/dist/agent/backends/gemini.js

@@ -1,3 +1,4 @@
+import { reasoningRequestParams } from '@zerg/model-contracts';
 import { BaseBackend } from './base.js';
 export class GeminiBackend extends BaseBackend {
     apiKey;
@@ -13,7 +14,7 @@ export class GeminiBackend extends BaseBackend {
             if (typeof content === 'string') {
                 return [{ text: content }];
             }
-            return content.map(block => {
+            return content.filter(block => block.type !== 'thinking' && block.type !== 'redacted_thinking').map(block => {
                 if (block.type === 'text') {
                     return { text: block.text };
                 }
@@ -33,6 +34,7 @@ export class GeminiBackend extends BaseBackend {
             });
         };
         const body = {
+            ...reasoningRequestParams('gemini', request.model, request.codexEffort),
             systemInstruction: { parts: [{ text: request.system }] },
             contents: request.messages.map(m => ({
                 role: m.role === 'assistant' ? 'model' : 'user',

package/dist/agent/backends/http_error.d.ts

@@ -0,0 +1,26 @@
+import type { HttpErrorDiagnostic } from './types.js';
+type BodyReadState = HttpErrorDiagnostic['bodyReadState'];
+/** Retains the canonical API-error envelope consumed by admission and OAuth adapters. */
+export declare class BackendHttpError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly httpError: HttpErrorDiagnostic;
+    /** Transport control only; never copied into the public body diagnostic. */
+    readonly retryAtMs?: number;
+    constructor(status: number, body: string, options?: {
+        prefix?: string;
+        headers?: RequestInit['headers'];
+        bodyReadState?: BodyReadState;
+        retryAfter?: string | null;
+        /** Router defines x-ratelimit-reset as relative seconds, not an epoch. */
+        rateLimitReset?: string | null;
+    });
+}
+/** Respect a server's minimum wait, then spread concurrent callers by up to one second. */
+export declare function retryAfterDelayMs(error: unknown): number;
+/** Read at most 16 KiB, then cancel. A failed body never erases already-known status. */
+export declare function readHttpErrorBody(response: Response, signal?: AbortSignal): Promise<{
+    body: string;
+    bodyReadState: BodyReadState;
+}>;
+export {};