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

package/dist/agent/backends/zrouter_stream.js

@@ -1,12 +1,15 @@
+import { modelContract, normalizeContractModel } from '@zerg/model-contracts';
+import { readRouterCatalog, resolveRouterModel } from '../../utils/router_catalog.js';
 import { randomUUID } from 'node:crypto';
 import { measureResponse, measureStream } from './request_metrics.js';
+import { BackendHttpError, readHttpErrorBody, retryAfterDelayMs } from './http_error.js';
 import { parseSSEEvents } from './sse.js';
 import { buildOpenAIMessages, buildOpenAIToolDefs } from './openai_format.js';
-import { buildKimiRequestParams, isKimiModel } from './kimi_params.js';
+import { isKimiModel } from './kimi_params.js';
 import { runtimeDiag } from '../../utils/debug_log.js';
 import { createZrouterEventMapper } from './zrouter_events.js';
 import { parseTokenUsage } from './token_usage.js';
-import { deepseekRequestParams, DEEPSEEK_FLASH_MAX_OUTPUT, isModalDeepSeekFlashModel, MODAL_DEEPSEEK_FLASH_MAX_OUTPUT, isDeepSeekFlashModel } from '../../utils/deepseek.js';
+import { DEEPSEEK_FLASH_MAX_OUTPUT, isModalDeepSeekFlashModel, MODAL_DEEPSEEK_FLASH_MAX_OUTPUT, isDeepSeekFlashModel } from '../../utils/deepseek.js';
 import { getVersion } from '../../utils/version.js';
 import { isTransportError } from './transport_errors.js';
 const ZROUTER_HEADERS_TIMEOUT_MS = 90_000;
@@ -23,19 +26,13 @@ const PINNABLE_DECORATION = /^[A-Za-z0-9._:-]{1,64}$/;
 function isPinnableDecoration(value) {
     return value !== undefined && PINNABLE_DECORATION.test(value);
 }
-// Transport reconnects must outlive a Router deploy or a Redis blip, not just a
-// lost packet: a Fly machine recycle RSTs every client's stream at once, so the
-// whole fleet sees "fetch failed" at the same moment. Three sub-second retries
-// used to hand a live turn back to the agent as a dead "Network error". Six
-// attempts with capped exponential backoff buy roughly 8-15s inside this
-// backend; the agent's own retry loop layers a second budget on top, and the
-// Router keeps buffering the producer under the same turn id the whole time, so
-// the reconnect resumes instead of restarting. Every knob is env-overridable
-// because a self-hosted Router may restart more slowly.
-const DEFAULT_RECONNECT_ATTEMPTS = 6;
-const DEFAULT_RECONNECT_BASE_MS = 500;
-const DEFAULT_RECONNECT_CAP_MS = 10_000;
-const MAX_RECONNECT_ATTEMPTS = 20;
+// Allow Router restarts to recover through bounded, cancellable retries. Each
+// reconnect reports progress and resumes the same turn/cursor. Hosts can tune
+// the attempt count and backoff through the environment.
+const DEFAULT_RECONNECT_ATTEMPTS = 120;
+const DEFAULT_RECONNECT_BASE_MS = 1_000;
+const DEFAULT_RECONNECT_CAP_MS = 30_000;
+const MAX_RECONNECT_ATTEMPTS = 120;
 const MAX_RECONNECT_MS = 300_000;
 function envBoundedInt(name, fallback, min, max) {
     const parsed = Number(process.env[name]);
@@ -59,6 +56,10 @@ function resolveReconnectPolicy() {
  * uses the unified chat endpoint so routing can fall back across providers.
  */
 export class ZRouterStreamBackend {
+    initialCatalog;
+    get catalog() {
+        return readRouterCatalog({ origin: this.proxyUrl, token: this.apiKey, workspaceId: this.workspaceId }) ?? this.initialCatalog;
+    }
     apiKey;
     proxyUrl;
     provider;
@@ -67,6 +68,7 @@ export class ZRouterStreamBackend {
     conversationId;
     clientName;
     constructor(config) {
+        this.initialCatalog = config.catalog ? structuredClone(config.catalog) : undefined;
         this.apiKey = config.apiKey;
         this.proxyUrl = config.proxyUrl.replace(/\/+$/, '');
         this.provider = config.provider;
@@ -87,12 +89,45 @@ export class ZRouterStreamBackend {
     handlesTransportRetries() {
         return true;
     }
+    getModelCapabilities(model) {
+        return this.catalog?.version === 1
+            ? resolveRouterModel(this.catalog, this.provider, model)?.capabilities : undefined;
+    }
     buildOpenAIBody(request) {
-        // ZTC stores the model separately from its provider. Router's global model
+        if (this.catalog?.version === 1) {
+            const descriptor = resolveRouterModel(this.catalog, this.provider, request.model);
+            if (!descriptor?.capabilities?.chat)
+                throw new Error('This model is no longer in the Router chat catalog. Refresh /model.');
+            const caps = descriptor.capabilities;
+            if (request.codexEffort && caps.reasoning && !caps.reasoning.choices.includes(request.codexEffort)) {
+                throw new Error(`Unsupported reasoning effort: ${request.codexEffort}`);
+            }
+            if (request.maxTokens !== undefined && caps.max_output_tokens !== undefined && request.maxTokens > caps.max_output_tokens) {
+                throw new Error(`Max output tokens exceeds the advertised limit (${caps.max_output_tokens}).`);
+            }
+            if (caps.images === false && request.messages.some(message => Array.isArray(message.content)
+                && message.content.some(block => block.type === 'image' || block.type === 'video')))
+                throw new Error('This model does not support images.');
+            const prepared = caps.tools === false ? chatOnlyRequest(request) : request;
+            return { provider: descriptor.owned_by, model: descriptor.id,
+                ...(request.routePlan ? { route: request.routePlan } : {}),
+                ...(request.maxTokens === undefined ? {} : { max_output_tokens: request.maxTokens }),
+                ...(caps.reasoning && request.codexEffort ? { reasoning_effort: request.codexEffort } : {}),
+                messages: buildOpenAIMessages(prepared),
+                ...(prepared.tools.length ? { tools: buildOpenAIToolDefs(prepared.tools) } : {}),
+            };
+        }
+        // Legacy contract for older Routers only. ZTC stores the model separately from its provider. Router's global model
         // namespace is a wire concern; keep existing namespaced IDs compatible.
         if (this.provider === 'modal' && !/^modal\//i.test(request.model)) {
             request = { ...request, model: `modal/${request.model}` };
         }
+        // Router resolves the Fireworks upstream id from the NAMESPACED form:
+        // fireworksUpstreamModelId returns null without the prefix and provider-client
+        // then answers 400 before dispatch. ZTC stores the bare slug, so add it here.
+        if (this.provider === 'fireworks') {
+            request = { ...request, model: `fireworks/${normalizeContractModel('fireworks', request.model)}` };
+        }
         // Kimi deprecates max_tokens in favour of max_completion_tokens, same as the
         // o-series and GPT-5+; keep this in step with the direct backend so the token
         // field does not depend on how the user authenticated.
@@ -115,20 +150,42 @@ export class ZRouterStreamBackend {
             model: request.model,
             ...(request.routePlan ? { route: request.routePlan } : {}),
             ...tokenParam,
-            // Kimi honors a reasoning_effort the picker exposes; without this the same
-            // selection applied on a direct key and vanished through the proxy.
-            // No-op for every non-Kimi model.
-            // Modal uses Kimi's effort ladder but keeps its own max_tokens contract.
-            ...buildKimiRequestParams(this.provider === 'modal'
-                ? { ...request, model: request.model.slice('modal/'.length) }
-                : request),
-            ...deepseekRequestParams(request),
+            ...(request.codexEffort && modelContract(this.provider, request.model, 'chat_tools')?.reasoningEfforts.includes(request.codexEffort)
+                ? { reasoning_effort: request.codexEffort } : {}),
             messages: buildOpenAIMessages(request),
             ...(request.tools.length > 0 ? { tools: buildOpenAIToolDefs(request.tools) } : {})
         };
     }
-    buildBody(request) {
-        return this.buildOpenAIBody(request);
+    serializeBody(request, stream = false) {
+        const body = {
+            ...this.buildOpenAIBody(request),
+            ...(stream ? { stream: true } : {}),
+        };
+        const serialized = JSON.stringify(body);
+        // Funded DeepSeek admission scans at most 10,000 JSON values, independently
+        // of the model's token window. A longer text history is otherwise rejected
+        // as non-text trial input, and resumable streaming masks that as a 5xx.
+        // Signal context overflow locally so hosts compact and retry, including
+        // when an agent's tool loop crosses the limit before returning to idle.
+        if (body.model === 'modal/deepseek-v4.1-flash'
+            || body.model === 'fireworks/deepseek-v4p1-flash') {
+            // Count the serialized wire shape: undefined properties disappear, and
+            // tool calls/results expand into separate messages during encoding.
+            const pending = [JSON.parse(serialized)];
+            let values = 1;
+            while (pending.length > 0) {
+                const value = pending.pop();
+                if (value === null || typeof value !== 'object')
+                    continue;
+                for (const child of Object.values(value)) {
+                    if (++values > 10_000) {
+                        throw new Error('Prompt is too long for Router\'s context structure limit (10,000 JSON values). Compact the conversation before retrying.');
+                    }
+                    pending.push(child);
+                }
+            }
+        }
+        return serialized;
     }
     async buildHeaders(request) {
         const token = this.authTokenProvider
@@ -141,6 +198,7 @@ export class ZRouterStreamBackend {
         const conversationPin = this.conversationPin(request);
         return {
             'Content-Type': 'application/json',
+            ...(this.catalog?.version === 1 ? { 'X-Zerg-Model-Contract': '1' } : {}),
             'Authorization': `Bearer ${normalizedToken}`,
             'X-Zerg-Client': this.clientName,
             'X-Zerg-Client-Version': getVersion(),
@@ -183,7 +241,7 @@ export class ZRouterStreamBackend {
         return measureResponse(routedRequest, fetcher => this.generateResponse(routedRequest, fetcher));
     }
     async generateResponse(request, fetcher) {
-        const body = this.buildBody(request);
+        const body = this.serializeBody(request);
         const headers = await this.buildHeaders(request);
         // Proof-chain log: the exact router endpoint + model this turn dispatches to.
         runtimeDiag('info', `[ztc] zrouter dispatch ${JSON.stringify({
@@ -195,15 +253,23 @@ export class ZRouterStreamBackend {
         const response = await fetcher(this.endpointFor(), {
             method: 'POST',
             headers,
-            body: JSON.stringify(body),
+            body,
             signal: request.signal,
         });
         if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`ZRouter API error (${response.status}): ${errorText}`);
+            const failure = await readHttpErrorBody(response, request.signal);
+            const error = new BackendHttpError(response.status, failure.body, { prefix: 'ZRouter API', headers,
+                bodyReadState: failure.bodyReadState, retryAfter: response.headers.get('retry-after'),
+                rateLimitReset: response.headers.get('x-ratelimit-reset') });
+            error.message += failureHeaderSuffix(response);
+            throw error;
         }
         const data = await response.json();
-        return this.parseOpenAIResponse(data);
+        const parsed = this.parseOpenAIResponse(data);
+        if (this.getModelCapabilities(request.model)?.tools === false && parsed.content.some(block => block.type === 'tool_use')) {
+            throw new Error('Chat-only model returned tools; execution is disabled.');
+        }
+        return parsed;
     }
     parseOpenAIResponse(data) {
         // ZRouter wraps OpenAI responses in OpenAI-compatible format
@@ -248,12 +314,15 @@ export class ZRouterStreamBackend {
         return measureStream(routedRequest, fetcher => this.streamResponse(routedRequest, fetcher));
     }
     async *streamResponse(request, fetcher) {
-        const body = { ...this.buildBody(request), stream: true };
+        const body = this.serializeBody(request, true);
         const mapEvent = createZrouterEventMapper();
         let resumeAfter;
         let emittedMappedEvent = false;
         let resumeSupported = false;
         const policy = resolveReconnectPolicy();
+        let reconnectStarted;
+        const budget = () => resumeAfter ? 300_000 : 30_000;
+        const remaining = () => budget() - (reconnectStarted === undefined ? 0 : Date.now() - reconnectStarted);
         for (let attempt = 1; attempt <= policy.attempts; attempt++) {
             try {
                 const headers = await this.buildHeaders(request);
@@ -262,12 +331,16 @@ export class ZRouterStreamBackend {
                 const response = await fetchWithHeadersTimeout(fetcher, this.endpointFor(), {
                     method: 'POST',
                     headers,
-                    body: JSON.stringify(body),
+                    body,
                     signal: request.signal,
-                }, ZROUTER_HEADERS_TIMEOUT_MS);
+                }, Math.min(ZROUTER_HEADERS_TIMEOUT_MS, Math.max(1, remaining())));
                 if (!response.ok) {
-                    const errorText = await response.text();
-                    throw new Error(`ZRouter API error (${response.status}): ${errorText}`);
+                    const failure = await readHttpErrorBody(response, request.signal);
+                    const error = new BackendHttpError(response.status, failure.body, { prefix: 'ZRouter API', headers,
+                        bodyReadState: failure.bodyReadState, retryAfter: response.headers.get('retry-after'),
+                        rateLimitReset: response.headers.get('x-ratelimit-reset') });
+                    error.message += failureHeaderSuffix(response);
+                    throw error;
                 }
                 if (!response.body) {
                     throw new Error('ZRouter API error: no response body for streaming request');
@@ -295,9 +368,12 @@ export class ZRouterStreamBackend {
                         const status = Number.isInteger(suppliedStatus) && suppliedStatus >= 400 && suppliedStatus <= 599
                             ? suppliedStatus
                             : 502;
-                        throw new Error(`ZRouter API error (${status}): ${JSON.stringify(ev.body ?? {})}`);
+                        throw new BackendHttpError(status, JSON.stringify(ev.body ?? {}), { prefix: 'ZRouter API', headers });
                     }
                     const mapped = mapEvent(ev);
+                    if (this.getModelCapabilities(request.model)?.tools === false && mapped.some(event => event.type.startsWith('tool_use'))) {
+                        throw new Error('Chat-only model returned tools; execution is disabled.');
+                    }
                     if (mapped.length > 0) {
                         // Heartbeats are liveness, not model output. A drop while only
                         // heartbeats have arrived cannot duplicate visible text, so it
@@ -317,8 +393,9 @@ export class ZRouterStreamBackend {
                 // emitted output. So a transient HTTP failure on a resume (the Router's
                 // coordination 503 while its shared store blips, a gateway 502/504) is
                 // retryable here, not just a raw socket error.
-                const retryable = isTransportError(error)
-                    || (resumeAfter !== undefined && isRetryableResumeStatus(error));
+                const retryable = error instanceof BackendHttpError
+                    ? resumeAfter !== undefined && isRetryableResumeStatus(error)
+                    : isTransportError(error);
                 if (request.signal?.aborted
                     || !retryable
                     || (emittedMappedEvent && (!resumeSupported || !resumeAfter))) {
@@ -328,15 +405,23 @@ export class ZRouterStreamBackend {
                     // second copy of the turn, so fail the attempt instead.
                     throw error;
                 }
-                if (attempt === policy.attempts)
+                reconnectStarted ??= Date.now();
+                const attempts = resumeAfter ? policy.attempts : Math.min(6, policy.attempts);
+                if (attempt >= attempts || remaining() <= 0)
                     throw error;
                 // The Router keeps producing under this turn id, so waiting costs the
                 // turn nothing: the next attempt resumes from the cursor, not from zero.
-                const delayMs = reconnectDelay(policy, attempt);
+                const delayMs = Math.min(Math.max(reconnectDelay(policy, attempt), retryAfterDelayMs(error)), remaining());
                 const reason = error instanceof Error ? error.message : String(error);
                 runtimeDiag('warn', `[ztc] zrouter stream dropped (${reason}); reconnecting in ${delayMs}ms (attempt ${attempt + 1}/${policy.attempts})`);
-                request.onTransportRetry?.({ attempt, maxAttempts: policy.attempts, delayMs, reason });
+                const publicReason = isRetryableResumeStatus(error)
+                    ? `Router temporarily unavailable ${reason.match(/\(\d{3}\)/)?.[0] ?? ''}. Resuming the response.`
+                    : reason;
+                request.onTransportRetry?.({ attempt, maxAttempts: attempts, delayMs, reason: publicReason,
+                    ...(error instanceof BackendHttpError && error.status === 429 ? { rateLimited: true } : {}) });
                 await waitForReconnect(delayMs, request.signal);
+                if (remaining() <= 0)
+                    throw error;
             }
         }
     }
@@ -387,6 +472,27 @@ async function waitForReconnect(delayMs, signal) {
         signal?.addEventListener('abort', abort, { once: true });
     });
 }
+/**
+ * Diagnostics that survive a body-less failure.
+ *
+ * A gateway that throws before it can classify anything often answers with a
+ * bare `Server Error` and puts the identifying information in the headers
+ * instead. Fly (Router's host) stamps a request id on every response; carrying
+ * it into the error is the only way to correlate a client-visible 500 with the
+ * server-side exception, since the body has nothing to correlate on.
+ *
+ * Bounded and header-only: never reads the body (already consumed), and caps
+ * each value so a hostile/proxied header cannot bloat an error message.
+ */
+function failureHeaderSuffix(response) {
+    const parts = [];
+    for (const name of ['fly-request-id', 'x-request-id', 'cf-ray', 'x-zerg-error-code']) {
+        const value = response.headers.get(name)?.trim();
+        if (value && value.length <= 128 && !/[\r\n\0]/.test(value))
+            parts.push(`${name}=${value}`);
+    }
+    return parts.length > 0 ? ` [${parts.join(' ')}]` : '';
+}
 /**
  * True for a `ZRouter API error (NNN)` a resume is worth retrying: a gateway or
  * rate-limit failure that is expected to clear. Kept separate from
@@ -415,3 +521,15 @@ function normalizeHeaderValue(value, label, maxLength) {
     }
     return normalized;
 }
+/** A wire-only projection: saved tool history remains byte-for-byte intact. */
+function chatOnlyRequest(request) {
+    return { ...request, tools: [], messages: request.messages.map(message => ({ ...message,
+            content: typeof message.content === 'string' ? message.content : message.content.map(block => {
+                if (block.type === 'tool_use')
+                    return { type: 'text', text: `Previous tool call ${block.name} (${block.id}): ${JSON.stringify(block.input)}` };
+                if (block.type === 'tool_result')
+                    return { type: 'text', text: `Previous tool result (${block.tool_use_id}): ${typeof block.content === 'string' ? block.content : block.content.map(part => part.type === 'text' ? part.text : '[image]').join('\n')}` };
+                return block;
+            }),
+        })) };
+}

package/dist/agent/background_registry.d.ts

@@ -13,6 +13,7 @@
  */
 import type { WorkerExecutor } from '../worker/index.js';
 import type { WorkerResult } from '../worker/index.js';
+import type { ModelUsageObserver } from '../types.js';
 export type BackgroundTaskStatus = 'running' | 'completed' | 'failed' | 'cancelled';
 /** Public view of a background task — omits internal abort machinery. */
 export interface BackgroundTaskInfo {
@@ -45,6 +46,7 @@ export interface BackgroundRegistryConfig {
     timeoutMs?: number;
 }
 export interface SpawnOptions {
+    onUsage?: ModelUsageObserver;
     maxIterations?: number;
     cwd?: string;
     timeoutMs?: number;

package/dist/agent/background_registry.js

@@ -73,6 +73,7 @@ export class BackgroundTaskRegistry {
                     task.status = 'running';
                 }
             },
+            onUsage: opts?.onUsage,
         })
             .then((result) => {
             // If already marked cancelled (by cancel() before abort propagated),

package/dist/agent/claim_observation.d.ts

@@ -0,0 +1,6 @@
+import type { HostClaimObservation, Message } from '../types.js';
+export declare function claimObservationWarning(basis: HostClaimObservation['basis']): string;
+/** Canonical message metadata; the original text, identity, and timestamp stay intact. */
+export declare function withHostClaimObservation(message: Message, basis: HostClaimObservation['basis'], toolCallCount: number, observedAt: Date): Message;
+/** This is a historical host observation, not proof that the requested work occurred. */
+export declare function assistantClaimReplayContent(message: Message): string;

package/dist/agent/claim_observation.js

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+export function claimObservationWarning(basis) {
+    return basis === 'no_tool_calls'
+        ? 'Heads up: the agent claimed completion without actually invoking any tools. '
+            + 'The task likely was not performed. Retry with a more specific instruction, '
+            + 'or break the work into smaller steps.'
+        : 'Heads up: the agent reported success while its own tool output showed errors. '
+            + 'Check the result above before trusting it, and retry if the work is incomplete.';
+}
+function sourceDigest(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/** Validate persisted observations against their unchanged authored source. */
+function validObservation(message, value) {
+    if (message.role !== 'assistant' || !value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value;
+    return Object.keys(record).length === 6
+        && record.version === 1
+        && typeof record.sourceMessageId === 'string'
+        && record.sourceMessageId === message.id
+        && Buffer.byteLength(record.sourceMessageId, 'utf8') > 0
+        && Buffer.byteLength(record.sourceMessageId, 'utf8') <= 256
+        && !/[\u0000-\u001f\u007f]/.test(record.sourceMessageId)
+        && record.sourceSha256 === sourceDigest(message.content)
+        && (record.basis === 'no_tool_calls' || record.basis === 'contradictory_tool_output')
+        && Number.isSafeInteger(record.toolCallCount)
+        && (record.basis === 'no_tool_calls' ? record.toolCallCount === 0 : record.toolCallCount > 0)
+        && typeof record.observedAt === 'string'
+        && record.observedAt.length === 24
+        && Number.isFinite(Date.parse(record.observedAt))
+        && new Date(record.observedAt).toISOString() === record.observedAt;
+}
+/** Canonical message metadata; the original text, identity, and timestamp stay intact. */
+export function withHostClaimObservation(message, basis, toolCallCount, observedAt) {
+    const observation = {
+        version: 1, sourceMessageId: message.id, sourceSha256: sourceDigest(message.content),
+        basis, toolCallCount, observedAt: observedAt.toISOString(),
+    };
+    if (!validObservation(message, observation))
+        throw new RangeError('Invalid host claim observation source or count');
+    return { ...message, metadata: { ...message.metadata, hostClaimObservation: observation } };
+}
+/** This is a historical host observation, not proof that the requested work occurred. */
+export function assistantClaimReplayContent(message) {
+    const observation = message.metadata?.hostClaimObservation;
+    if (!validObservation(message, observation))
+        return message.content;
+    return '[Unverified assistant claim; historical host observation for source '
+        + JSON.stringify(observation.sourceMessageId) + ' at ' + observation.observedAt + ']\n'
+        + claimObservationWarning(observation.basis) + '\n'
+        + 'Treat the following original statement as unverified, not as evidence of completed work:\n'
+        + message.content;
+}