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

package/dist/agent/backends/openai_responses.js

@@ -99,23 +99,35 @@ function isValidResponsesTerminalEvent(eventType, value, observedOutput) {
         && value.status === expectedStatus
         && isValidResponsesTerminal(value, observedOutput);
 }
-export const MAX_RESPONSES_RESPONSE_BYTES = 1_048_576;
-function responseLimitError() {
-    return new Error(`Responses API response exceeded ${MAX_RESPONSES_RESPONSE_BYTES} bytes`);
+export const MAX_RESPONSES_RESPONSE_BYTES = 64 * 1024 * 1024;
+export const MAX_PROVIDER_ERROR_BYTES = 64 * 1024;
+export const MAX_RESPONSES_SSE_EVENT_BYTES = 8 * 1024 * 1024;
+// One turn cannot retain an unbounded sequence of individually valid items.
+export const MAX_RESPONSES_SSE_STREAM_BYTES = 32 * 1024 * 1024;
+class ResponsesBodyLimitError extends Error {
+    constructor(maxBytes) {
+        super(`Responses API response exceeded ${maxBytes} bytes`);
+    }
+}
+function responseLimitError(maxBytes) {
+    return new ResponsesBodyLimitError(maxBytes);
 }
-function rejectOversizedDeclaredBody(response) {
+function rejectOversizedDeclaredBody(response, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        throw new Error('Responses API byte limit must be a positive safe integer');
+    }
     const declaredLength = Number(response.headers.get('content-length'));
-    if (Number.isFinite(declaredLength) && declaredLength > MAX_RESPONSES_RESPONSE_BYTES) {
-        throw responseLimitError();
+    if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+        throw responseLimitError(maxBytes);
     }
 }
 /** Read a provider body without allowing fetch helpers to buffer it without limit. */
-export async function readBoundedResponsesText(response) {
-    rejectOversizedDeclaredBody(response);
+export async function readBoundedResponsesText(response, maxBytes = MAX_RESPONSES_RESPONSE_BYTES) {
+    rejectOversizedDeclaredBody(response, maxBytes);
     if (!response.body) {
         const text = await response.text();
-        if (Buffer.byteLength(text, 'utf8') > MAX_RESPONSES_RESPONSE_BYTES) {
-            throw responseLimitError();
+        if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+            throw responseLimitError(maxBytes);
         }
         return text;
     }
@@ -128,9 +140,9 @@ export async function readBoundedResponsesText(response) {
             const { done, value } = await reader.read();
             if (done)
                 break;
-            if (totalBytes + value.byteLength > MAX_RESPONSES_RESPONSE_BYTES) {
+            if (totalBytes + value.byteLength > maxBytes) {
                 await reader.cancel().catch(() => undefined);
-                throw responseLimitError();
+                throw responseLimitError(maxBytes);
             }
             totalBytes += value.byteLength;
             parts.push(decoder.decode(value, { stream: true }));
@@ -142,6 +154,19 @@ export async function readBoundedResponsesText(response) {
         reader.releaseLock();
     }
 }
+/** Keep the HTTP status authoritative when an oversized diagnostic must be omitted. */
+export async function readBoundedProviderError(response) {
+    try {
+        return await readBoundedResponsesText(response, MAX_PROVIDER_ERROR_BYTES);
+    }
+    catch (error) {
+        if (!(error instanceof ResponsesBodyLimitError))
+            throw error;
+        // Declared oversize responses fail before acquiring a reader; cancel those too.
+        await response.body?.cancel().catch(() => undefined);
+        return `Provider response exceeded ${MAX_PROVIDER_ERROR_BYTES} bytes; body omitted.`;
+    }
+}
 // ─── Exported helpers for input/output conversion ───────────────────
 /** Convert internal LlmMessage[] into Responses API input items. */
 export function buildResponsesInput(messages) {
@@ -281,8 +306,9 @@ export function parseResponsesOutput(data) {
  * request was sent with `stream: true`). If the body isn't readable (rare), it
  * buffers the SSE text and parses it whole — the same events, just not live.
  */
-export async function* streamResponsesSSE(response) {
-    rejectOversizedDeclaredBody(response);
+export async function* streamResponsesSSE(response, maxBytes = MAX_RESPONSES_SSE_STREAM_BYTES) {
+    rejectOversizedDeclaredBody(response, maxBytes);
+    const streamLimit = Math.min(maxBytes, MAX_RESPONSES_SSE_STREAM_BYTES);
     const outputItems = [];
     let usage;
     let terminalEventSeen = false;
@@ -371,49 +397,67 @@ export async function* streamResponsesSSE(response) {
     if (response.body) {
         const reader = response.body.getReader();
         const decoder = new TextDecoder();
-        let buffer = '';
+        const lineParts = [];
+        let lineBytes = 0;
         let totalBytes = 0;
+        const appendLinePart = (part) => {
+            lineBytes += Buffer.byteLength(part, 'utf8');
+            if (lineBytes > MAX_RESPONSES_SSE_EVENT_BYTES) {
+                throw new Error(`Responses SSE event exceeded ${MAX_RESPONSES_SSE_EVENT_BYTES} bytes`);
+            }
+            if (part)
+                lineParts.push(part);
+        };
         try {
             for (;;) {
                 const { done, value } = await reader.read();
                 if (done)
                     break;
-                const remaining = MAX_RESPONSES_RESPONSE_BYTES - totalBytes;
+                const remaining = streamLimit - totalBytes;
                 const overflow = value.byteLength > remaining;
-                const accepted = overflow ? value.subarray(0, Math.max(0, remaining)) : value;
+                const accepted = overflow ? value.subarray(0, remaining) : value;
                 totalBytes += accepted.byteLength;
-                buffer += decoder.decode(accepted, { stream: true });
+                const decoded = decoder.decode(accepted, { stream: true });
+                let offset = 0;
                 let nl;
-                while ((nl = buffer.indexOf('\n')) >= 0) {
-                    handleLine(buffer.slice(0, nl));
-                    buffer = buffer.slice(nl + 1);
-                    // Drain per-line, not per-chunk: a delta and response.failed can share a
-                    // single chunk. If we buffered until every line parsed, handleLine would
-                    // throw on the failure BEFORE the queued delta yields — the agent would
-                    // then see no delta and re-call generate() as a buffered fallback.
+                // Search only newly decoded bytes. Join a split line once, when its
+                // delimiter arrives, instead of repeatedly rescanning its full prefix.
+                while ((nl = decoded.indexOf('\n', offset)) >= 0) {
+                    appendLinePart(decoded.slice(offset, nl));
+                    handleLine(lineParts.join(''));
+                    lineParts.length = 0;
+                    lineBytes = 0;
+                    offset = nl + 1;
                     while (pending.length)
                         yield pending.shift();
                 }
+                appendLinePart(decoded.slice(offset));
                 if (overflow) {
-                    await reader.cancel().catch(() => undefined);
-                    throw responseLimitError();
+                    if (maxBytes < MAX_RESPONSES_SSE_STREAM_BYTES)
+                        throw responseLimitError(maxBytes);
+                    throw new Error(`Responses SSE stream exceeded ${MAX_RESPONSES_SSE_STREAM_BYTES} bytes`);
                 }
             }
-            // Flush a trailing line with no terminating newline (spec-valid) — else
-            // the final response.completed (usage) / last item would be lost.
-            if (buffer.trim())
-                handleLine(buffer);
+            appendLinePart(decoder.decode());
+            if (lineParts.length)
+                handleLine(lineParts.join(''));
             while (pending.length)
                 yield pending.shift();
         }
+        catch (error) {
+            await reader.cancel().catch(() => undefined);
+            throw error;
+        }
         finally {
             reader.releaseLock();
         }
     }
     else {
         // No streamable body (rare) — buffer the SSE text and parse it whole.
-        const text = await readBoundedResponsesText(response);
+        const text = await readBoundedResponsesText(response, streamLimit);
         for (const rawLine of text.split('\n')) {
+            if (Buffer.byteLength(rawLine, 'utf8') > MAX_RESPONSES_SSE_EVENT_BYTES)
+                throw new Error(`Responses SSE event exceeded ${MAX_RESPONSES_SSE_EVENT_BYTES} bytes`);
             handleLine(rawLine);
             // Drain per-line so a same-payload delta yields before a later failure throws.
             while (pending.length)
@@ -520,7 +564,7 @@ export class OpenAIResponsesBackend extends BaseBackend {
                 'Check network access, proxy configuration, and API key/model access.');
         }
         if (!response.ok) {
-            const errorText = await readBoundedResponsesText(response);
+            const errorText = await readBoundedProviderError(response);
             throw new Error(`API error (${response.status}): ${errorText}`);
         }
         return response;

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

@@ -7,3 +7,4 @@ export declare function normalizeProviderId(provider: string): string;
 export declare function isCodexAppServerProvider(provider: string): boolean;
 export declare function isCodexLegacyProvider(provider: string): boolean;
 export declare function getProviderDisplayName(provider: string): string;
+export declare function isLocalSubscriptionProvider(provider: string): boolean;

package/dist/agent/backends/provider_ids.js

@@ -37,3 +37,7 @@ export function getProviderDisplayName(provider) {
             return provider;
     }
 }
+export function isLocalSubscriptionProvider(provider) {
+    return ['codex_app_server', 'codex_legacy', 'claude_code', 'claude-code', 'claude_code_direct', 'claude-code-direct', 'kimi_code', 'kimi-code']
+        .includes(normalizeProviderId(provider));
+}

package/dist/agent/backends/request_metrics.js

@@ -1,7 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import { isIncompleteModelResponse } from '../completion_state.js';
 import { transportErrorCode } from './transport_errors.js';
-/** One collector per logical backend call. Contains counters and timings, never prompts or credentials. */
+import { BackendHttpError } from './http_error.js';
+/** One collector per logical backend call, with timings and bounded, redacted HTTP failure details. */
 class RequestMeter {
     request;
     metrics;
@@ -81,11 +82,16 @@ class RequestMeter {
             this.metrics.outcome = isIncompleteModelResponse(event.stopReason) ? 'error' : 'success';
     }
     observeStreamError(error) {
+        this.observeError(error);
         const attempt = this.metrics.transportAttempts?.at(-1);
         if (!attempt || attempt.phase === 'before_headers')
             return;
         attempt.phase = 'stream';
-        attempt.errorCode = transportErrorCode(error);
+        attempt.errorCode = transportErrorCode(error) ?? attempt.errorCode;
+    }
+    observeError(error) {
+        if (error instanceof BackendHttpError)
+            this.metrics.httpError = error.httpError;
     }
     finish() {
         this.metrics.totalMs = this.elapsed();
@@ -105,6 +111,10 @@ export async function measureResponse(request, generate) {
         meter.metrics.outcome = isIncompleteModelResponse(response.stopReason) ? 'error' : 'success';
         return response;
     }
+    catch (error) {
+        meter.observeError(error);
+        throw error;
+    }
     finally {
         meter.finish();
     }

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

@@ -1,5 +1,4 @@
-import { ToolDefinition } from '../../types.js';
-import type { Message } from '../../types.js';
+import type { ToolDefinition, Message } from '../../types.js';
 export interface RequestTextBlock {
     type: 'text';
     text: string;
@@ -37,7 +36,17 @@ export interface ToolUseRequestBlock {
     name: string;
     input: Record<string, unknown>;
 }
-export type RequestContentBlock = RequestTextBlock | RequestImageBlock | RequestVideoBlock | ToolResultBlock | ToolUseRequestBlock;
+export interface ThinkingBlock {
+    type: 'thinking';
+    thinking: string;
+    /** Opaque provider signature; never alter or synthesize it. */
+    signature: string;
+}
+export interface RedactedThinkingBlock {
+    type: 'redacted_thinking';
+    data: string;
+}
+export type RequestContentBlock = RequestTextBlock | RequestImageBlock | RequestVideoBlock | ToolResultBlock | ToolUseRequestBlock | ThinkingBlock | RedactedThinkingBlock;
 export interface LlmMessage {
     role: 'user' | 'assistant';
     content: string | RequestContentBlock[];
@@ -56,7 +65,7 @@ export interface ToolUseBlock {
     name: string;
     input: Record<string, unknown>;
 }
-export type ContentBlock = TextBlock | ToolUseBlock;
+export type ContentBlock = TextBlock | ToolUseBlock | ThinkingBlock | RedactedThinkingBlock;
 /**
  * An action surfaced by a provider that runs its OWN tool/command loop (e.g. the
  * official Codex App Server). Unlike ZTC-owned tool calls — where the model
@@ -65,6 +74,13 @@ export type ContentBlock = TextBlock | ToolUseBlock;
  * of showing only the provider's final prose. See `codex_app_server.ts`.
  */
 export type BackendObservation = {
+    /** Provider-scoped invocation identity; never a host execution receipt. */
+    native?: {
+        provider: string;
+        threadId: string;
+        turnId: string;
+    };
+} & ({
     kind: 'command';
     id: string;
     command: string;
@@ -83,11 +99,69 @@ export type BackendObservation = {
     label: string;
     detail?: Record<string, unknown>;
     output?: string;
+    status?: string;
+    artifacts?: Array<{
+        path: string;
+        sha256?: string;
+    }>;
+    partial?: boolean;
+    isError?: boolean;
+});
+export type BufferedRecoveryPolicy = {
+    version: 'codex-buffered-idle-v1' | 'codex-buffered-idle-overload-v1' | 'codex-buffered-idle-overload-interrupted-v1';
+    idleTimeoutMs: 8000;
+} | {
+    version: 'codex-buffered-idle-overload-duration-v1' | 'codex-buffered-idle-overload-duration-interrupted-v1';
+    idleTimeoutMs: 8000;
+    firstBodyTimeoutMs: 30000;
+};
+export interface BufferedTransportAttempt {
+    /** Absent in legacy wall-clock captures. New stamps use one anchored monotonic clock. */
+    timingClock?: 'monotonic-epoch-v1';
+    type: 'started' | 'settled';
+    attempt: number;
+    trigger: 'initial' | 'body-idle' | 'auth-refresh' | 'provider-overload' | 'body-duration' | 'body-interrupted';
+    bodySha256: string;
+    bodyBytes: number;
+    startedAtMs: number;
+    deadlineAtMs: number;
+    headersAtMs?: number;
+    status?: number;
+    bytes: number;
+    chunks: number;
+    /** Final logical usage is separate; a cancelled physical attempt's cost is unknown. */
+    usage: 'unknown';
+    firstChunkAtMs?: number;
+    lastChunkAtMs?: number;
+    semanticTerminal?: string;
+    semanticTerminalAtMs?: number;
+    providerFailure?: 'provider-overload';
+    eofAtMs?: number;
+    abortAtMs?: number;
+    cancelledAtMs?: number;
+    endedAtMs?: number;
+    reason?: 'complete' | 'idle' | 'abort' | 'http-error' | 'transport-error' | 'consumer-cancel' | 'body-duration' | 'body-interrupted';
+}
+export type BufferedRecoveryRequest = BufferedRecoveryPolicy & {
+    deadlineAtMs: number;
+    onAttempt?: (event: BufferedTransportAttempt) => void;
 };
 export interface BackendRequest {
     model: string;
     /** Omit to use the provider default; numeric values are explicit caps. */
     maxTokens?: number;
+    /** Explicit buffered Codex opt-in. Streaming and absent options keep legacy behavior. */
+    bufferedRecovery?: BufferedRecoveryRequest;
+    /** Codex subscription transport cap, including SSE framing and repeated output.
+     * This bounds client consumption, not hidden reasoning or billed tokens.
+     * Absent keeps the Codex 1 MiB default; simulations explicitly allow 8 MiB. */
+    maxResponseBytes?: number;
+    /** Codex subscription only: append "Aim for at most <maxTokens> output tokens."
+     * to the instructions. Simulations opt in; the agent does not. */
+    outputTokenGuidance?: boolean;
+    /** Schema guidance for Codex responses. Callers still validate returned JSON. */
+    outputSchema?: Record<string, unknown>;
+    outputSchemaStrict?: boolean;
     system: string;
     messages: LlmMessage[];
     tools: ToolDefinition[];
@@ -151,8 +225,11 @@ export interface BackendRequest {
     /**
      * Sink for provider-owned tool/command observations (Codex App Server runs its
      * own harness). Backends that own execution call this as each action completes;
-     * the agent maps observations to tool_start/tool_end/reasoning_delta events so
-     * they appear in the mirror. Ignored by ZTC-tool-calling backends.
+     * the agent retains bounded command/action reports as provider_reported and
+     * maps them to the canonical evidence and display events. Private reasoning
+     * is display-only. Native adapters await asynchronous sinks before completing
+     * a turn; the Agent also drains capture for synchronous callback producers.
+     * Ignored by ZTC-tool-calling backends.
      */
     onObservation?: (observation: BackendObservation) => void;
     /**
@@ -174,6 +251,7 @@ export interface BackendRequest {
         maxAttempts: number;
         delayMs: number;
         reason: string;
+        rateLimited?: boolean;
     }) => void;
     /** Per HTTP attempt diagnostics for Router and OpenAI-compatible transports. */
     onMetrics?: (metrics: RequestMetrics) => void;
@@ -202,7 +280,10 @@ export interface ClientToolCallResult {
 export interface BackendResponse {
     content: ContentBlock[];
     stopReason: string;
+    stopDetails?: Record<string, unknown>;
     usage?: TokenUsage;
+    /** Explicit provider-reported USD, independent from token accounting or inferred pricing. */
+    costUsd?: number;
     /** Provider-specific opaque reasoning trace (e.g. Kimi/Moonshot thinking
      *  models). Persisted on the assistant turn so it can be replayed on the
      *  next request — moonshot rejects assistant tool-call replays without it. */
@@ -240,6 +321,11 @@ export type StreamEvent = {
 } | {
     type: 'text_delta';
     text: string;
+}
+/** Completed native block, in provider order, alongside live display deltas. */
+ | {
+    type: 'content_block';
+    block: ContentBlock;
 } | {
     type: 'tool_use_start';
     id: string;
@@ -254,11 +340,18 @@ export type StreamEvent = {
 } | {
     type: 'usage';
     usage: TokenUsage;
+} | {
+    type: 'cost';
+    costUsd: number;
 } | {
     type: 'done';
     stopReason: string;
+    stopDetails?: Record<string, unknown>;
 };
 export interface AgentBackend {
+    /** Preserve ordered provider blocks and previously submitted context bytes. */
+    readonly preservesNativeHistory?: boolean;
+    getModelCapabilities?(model: string): import('../../utils/router_catalog.js').RouterModelCapabilities | undefined;
     /** Deliver user input into a provider-owned active turn when supported. */
     steerUserMessage?(message: Message): Promise<boolean>;
     /**
@@ -287,6 +380,8 @@ export interface AgentBackend {
     streamsSyntheticallyFor?(request: BackendRequest): boolean;
     /** False when a stream retry must stay on the resumable streaming contract. */
     allowsBufferedFallbackAfterStreamFailure?(request: BackendRequest): boolean;
+    /** Native harnesses return false once dispatch may have produced external effects. */
+    allowsRequestRetryAfterFailure?(request: BackendRequest): boolean;
     /**
      * True when the backend correlates a logical turn across transport reconnects
      * (it stamps a `transportTurnId` so the Router can resume the same buffered
@@ -307,6 +402,8 @@ export interface RequestMetrics {
     requestId: string;
     outcome: 'success' | 'error' | 'aborted';
     status?: number;
+    /** Bounded, redacted failure body; never request headers or raw credentials. */
+    httpError?: HttpErrorDiagnostic;
     clientPrepareMs?: number;
     headersMs?: number;
     firstReasoningMs?: number;
@@ -318,6 +415,12 @@ export interface RequestMetrics {
     transportAttempts?: TransportAttemptMetrics[];
     usage?: TokenUsage;
 }
+export interface HttpErrorDiagnostic {
+    status: number;
+    body: string;
+    bodyTruncated: boolean;
+    bodyReadState: 'complete' | 'truncated' | 'failed' | 'timeout';
+}
 export interface TransportAttemptMetrics {
     attemptId: string;
     status?: number;

package/dist/agent/backends/types.js

@@ -4,6 +4,7 @@ export function* syntheticStreamEvents(response) {
         yield { type: 'reasoning_delta', text: response.reasoning };
     }
     for (const block of response.content) {
+        yield { type: 'content_block', block };
         if (block.type === 'text') {
             yield { type: 'text_delta', text: block.text };
         }
@@ -16,5 +17,8 @@ export function* syntheticStreamEvents(response) {
     if (response.usage) {
         yield { type: 'usage', usage: response.usage };
     }
-    yield { type: 'done', stopReason: response.stopReason };
+    if (typeof response.costUsd === 'number' && Number.isFinite(response.costUsd) && response.costUsd >= 0) {
+        yield { type: 'cost', costUsd: response.costUsd };
+    }
+    yield { type: 'done', stopReason: response.stopReason, ...(response.stopDetails ? { stopDetails: response.stopDetails } : {}) };
 }

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

@@ -1,5 +1,7 @@
+import type { RouterCatalog, RouterModelCapabilities } from '../../utils/router_catalog.js';
 import { AgentBackend, BackendRequest, BackendResponse, StreamEvent } from './types.js';
 export interface ZRouterStreamConfig {
+    catalog?: RouterCatalog;
     apiKey: string;
     proxyUrl: string;
     provider: string;
@@ -26,6 +28,8 @@ export interface ZRouterStreamConfig {
  * uses the unified chat endpoint so routing can fall back across providers.
  */
 export declare class ZRouterStreamBackend implements AgentBackend {
+    private readonly initialCatalog?;
+    private get catalog();
     private apiKey;
     private proxyUrl;
     private provider;
@@ -38,8 +42,9 @@ export declare class ZRouterStreamBackend implements AgentBackend {
     isAuthenticationConfigured(): boolean;
     allowsBufferedFallbackAfterStreamFailure(): boolean;
     handlesTransportRetries(): boolean;
+    getModelCapabilities(model: string): RouterModelCapabilities | undefined;
     private buildOpenAIBody;
-    private buildBody;
+    private serializeBody;
     private buildHeaders;
     /**
      * The conversation identity this turn declares to Router, which forwards it to