@juspay/neurolink 12.17.1 → 12.17.3

package/dist/types/proxy.d.ts

@@ -1,3 +1,5 @@
+import type { ProxyTokenBudgetSnapshot } from "./proxyBudget.js";
+import type { ProxyContextEvidence, ProxyPreparedContext } from "./proxyContext.js";
 /**
  * Proxy type definitions for NeuroLink
  *
@@ -556,6 +558,27 @@ export type ProxyAccountSortMetrics = {
     scopedSaturated: boolean;
 };
 export type RequestLogEntry = {
+    /** Whether model identifies observed serving output rather than a routing target. */
+    servingModelStatus?: "observed" | "unavailable";
+    /** Whether retrying unchanged input can resolve this terminal failure. */
+    retryable?: boolean;
+    tokenBudget?: ProxyTokenBudgetSnapshot;
+    contextPreflight?: ProxyContextEvidence;
+    /** Internal adapter requests link to their one client-facing parent. */
+    parentRequestId?: string;
+    accountingScope?: "client" | "internal";
+    /** Exactly this request owns usage; bridge parents never duplicate it. */
+    usageOwnerRequestId?: string;
+    /** API price-table estimate, never a subscription charge or quota measure.
+     * Null when complete usage and an exact model rate are not both available. */
+    apiEquivalentCostUsd?: number | null;
+    /** API-equivalent cache-read savings against uncached input at the same rate. */
+    apiEquivalentCacheSavingsUsd?: number | null;
+    pricingStatus?: "exact" | "inferred" | "unavailable" | "usage_incomplete" | "owned_by_child";
+    pricingBasis?: "api_price_table";
+    pricingProvider?: string;
+    /** Credential identity is unavailable when the SDK does not expose it. */
+    accountIdentityStatus?: "observed" | "unavailable";
     /** First text, refusal or populated tool output, excluding SSE control frames. */
     firstUsefulOutputMs?: number;
     /** Why first-useful-output timing is absent; never substitute a zero. */
@@ -646,7 +669,10 @@ export type ProcessedProxyBodyCapture = {
     headers?: Record<string, string>;
     stored: StoredBodyArtifact;
     error?: string;
+    /** Admission plus worker queue time; retained for existing consumers. */
     queueWaitMs?: number;
+    admissionWaitMs?: number;
+    workerQueueWaitMs?: number;
     processingMs?: number;
     admission?: ProxyBodyCaptureAdmission;
 };
@@ -662,6 +688,11 @@ export type ProxyBodyCaptureAdmission = {
     maxPendingBytes: number;
 };
 export type ProxyBodyCaptureWorkerSnapshot = {
+    processing?: number;
+    publishing?: number;
+    oldestAdmissionWaitMs?: number;
+    oldestProcessingMs?: number;
+    oldestPublicationMs?: number;
     attempted: number;
     completed: number;
     rejected: number;
@@ -686,6 +717,13 @@ export type ProxyBodyDeliveryResult = {
     unconfirmedChunks: number;
     droppedChunks: number;
     notSubmittedChunks?: number;
+    /** Total publication elapsed time, including capacity and exporter waits. */
+    publicationMs?: number;
+    capacityWaitMs?: number;
+    /** Maximum per-chunk residence before an OTLP export starts. */
+    maxChunkQueueWaitMs?: number;
+    /** Maximum per-chunk transport duration; never sums overlapping exports. */
+    maxChunkExportMs?: number;
     reason?: string;
 };
 /** One bounded body publication, tracked across exporter callbacks. */
@@ -694,6 +732,8 @@ export type ProxyBodyPublicationProgress = {
     unconfirmed: number;
     dropped: number;
     emitted: number;
+    maxChunkQueueWaitMs?: number;
+    maxChunkExportMs?: number;
     notify?: () => void;
 };
 /** Bounded metadata-only evidence for an unconfirmed or locally rejected OTLP batch. */
@@ -714,6 +754,8 @@ export type ProxyTelemetryBackend = {
     baseUrl: string;
     organization: string;
     stream: string;
+    /** Optional separate backend storage for bulk body chunks. */
+    bodyStream?: string;
     authorization?: string;
     collectorMetricsUrl?: string;
 };
@@ -741,6 +783,10 @@ export type ProxyTelemetryDoctorOptions = {
     endTime: number;
     proxyUrl?: string;
     maxRows?: number;
+    /** Explicit age-search horizon; older admissions are outside this proof. */
+    admissionLookbackMs?: number;
+    requestTimeoutMs?: number;
+    ingestionGraceMs?: number;
     fetchImpl?: typeof fetch;
 };
 export type ProxyTelemetryCheck = {
@@ -766,6 +812,8 @@ export type ProxyTelemetryStoredRecord = Partial<RequestLogEntry> & {
     event?: string;
     telemetryStatus?: string;
     outcomeSource?: string;
+    requestTimeoutMs?: number;
+    redactionLossy?: boolean;
 };
 export type ProxyTelemetryFieldCoverage = {
     records: number;
@@ -786,6 +834,14 @@ export type ProxyRequestLoggerSnapshot = {
     debug: ProxyRequestLogSinkSnapshot;
 };
 export type RequestAttemptLogEntry = {
+    /** False for a local context/budget refusal before a provider call. */
+    upstreamDispatched?: boolean;
+    /** Client model name retained independently of the dispatched model. */
+    requestedModel?: string;
+    tokenBudget?: ProxyTokenBudgetSnapshot;
+    contextPreflight?: ProxyContextEvidence;
+    accountingScope?: "client" | "internal";
+    usageOwnerRequestId?: string;
     timestamp: string;
     requestId: string;
     /** Parent client request for an internal fallback invocation. */
@@ -825,10 +881,14 @@ export type RequestAttemptLogEntry = {
     quotaResetAt?: number;
     /** Unknown scope never implies an account-wide long-window rejection. */
     quotaScope?: "session" | "weekly" | "unknown";
+    /** True when input includes the cache breakdown (native Codex wire usage). */
+    inputIncludesCachedTokens?: boolean;
     inputTokens?: number;
     outputTokens?: number;
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
+    /** Reasoning tokens are a subset of output, never additional usage. */
+    reasoningTokens?: number;
     /** Provider that received this upstream attempt. */
     provider?: string;
     /** OTel trace ID for correlation with distributed traces */
@@ -839,9 +899,9 @@ export type RequestAttemptLogEntry = {
     traceFlags?: number;
 };
 /** Additional fields recorded when a Codex response becomes client-final. */
-export type CodexFinalLogExtra = Partial<Pick<RequestLogEntry, "errorType" | "errorMessage" | "errorCode" | "transportScope" | "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheCreationTokens" | "reasoningTokens" | "terminalOutcome" | "firstUsefulOutputMs" | "firstUsefulOutputStatus" | "firstUsefulOutputEvent">>;
+export type CodexFinalLogExtra = Partial<Pick<RequestLogEntry, "errorType" | "errorMessage" | "errorCode" | "transportScope" | "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheCreationTokens" | "reasoningTokens" | "terminalOutcome" | "firstUsefulOutputMs" | "firstUsefulOutputStatus" | "firstUsefulOutputEvent" | "retryable">>;
 /** Additional fields recorded for each upstream Codex account attempt. */
-export type CodexAttemptLogExtra = Partial<Pick<RequestAttemptLogEntry, "errorType" | "errorMessage" | "errorCode" | "transportScope" | "retryable" | "rateLimitKind" | "cooldownReason" | "quotaResetAt" | "quotaScope">>;
+export type CodexAttemptLogExtra = Partial<Pick<RequestAttemptLogEntry, "inputTokens" | "outputTokens" | "cacheReadTokens" | "cacheCreationTokens" | "reasoningTokens" | "inputIncludesCachedTokens" | "errorType" | "errorMessage" | "errorCode" | "transportScope" | "retryable" | "rateLimitKind" | "cooldownReason" | "quotaResetAt" | "quotaScope">>;
 /** Minimal persistence contract needed by Codex rotating-token refreshes. */
 export type CodexRefreshTokenStore = {
     peekTokens(provider: string): Promise<StoredOAuthTokens | null>;
@@ -876,6 +936,7 @@ export type ClaudeFinalRequestLogger = (status: number, accountLabel: string, ac
     cacheReadTokens?: number;
     reasoningTokens?: number;
     errorCode?: string;
+    retryable?: boolean;
     transportScope?: ProxyTransportScope;
 }) => void;
 export type ClaudeLoggedErrorBuilder = (status: number, message: string, errorType?: string, extra?: {
@@ -883,6 +944,7 @@ export type ClaudeLoggedErrorBuilder = (status: number, message: string, errorTy
     accountType?: string;
     attempt?: number;
     errorCode?: string;
+    retryable?: boolean;
     transportScope?: ProxyTransportScope;
 }) => ClaudeErrorResponse;
 export type ClaudeRequestRuntimeContext = {
@@ -935,6 +997,7 @@ export type AnthropicLoopState = {
 export type AnthropicUpstreamBody = {
     bodyStr: string;
     sessionId?: string;
+    preparedContext: ProxyPreparedContext<ClaudeRequest>;
 };
 export type AnthropicUpstreamBodyBuilder = (token: string) => AnthropicUpstreamBody;
 export type LoadedClaudeAccountContext = {
@@ -1044,6 +1107,7 @@ export type PreparedAnthropicAccountAttempt = {
     headers?: Record<string, string>;
     buildUpstreamBody?: AnthropicUpstreamBodyBuilder;
     finalBodyStr?: string;
+    preparedContext?: ProxyPreparedContext<ClaudeRequest>;
     fetchStartMs?: number;
     upstreamSpan?: Span;
 };
@@ -1681,8 +1745,12 @@ export type ProxyRequestContext = {
      * every non-Anthropic model prices to $0.
      */
     provider?: string;
-    /** An internal fallback is an attempt; its parent owns request/token metrics. */
+    /** Whether this span owns client request, latency, and error metrics. */
     recordRequestMetrics?: boolean;
+    /** Provider usage ownership. Defaults to recordRequestMetrics for backwards
+     * compatibility: internal Codex fallback spans suppress both, while bridge
+     * children explicitly retain usage and their parent owns client outcomes. */
+    recordUsageMetrics?: boolean;
 };
 /** Response-side details parsed from the upstream reply (model, finish, tools). */
 export type ResponseInfoContext = {
@@ -1722,6 +1790,11 @@ export type UsageContext = {
     rateLimitAfter5h?: number;
     rateLimitAfter7d?: number;
 };
+/** Keep trace usage when a child request owns its token and cost metrics. */
+export type ProxyUsageAttributionOptions = {
+    /** Defaults to the tracer's configured ownership when omitted. */
+    recordMetrics?: boolean;
+};
 /** Where a proxy env file path was sourced from. */
 export type ProxyEnvSource = "cli" | "environment" | "default" | "none";
 /** Result of resolving which proxy env file to load. */
@@ -1765,6 +1838,11 @@ export type ProxyActivitySnapshot = {
 export type ProxyRuntimeActivity = {
     activeRequests: number;
     lastActivityAt: string | null;
+    /** Supervisor-wide resources that must settle before process replacement. */
+    drainingWorkers?: number;
+    queuedSockets?: number;
+    pendingTransfers?: number;
+    candidateWorkers?: number;
 };
 /** Terminal state observed while the HTTP adapter relays a response body. */
 export type ProxyResponseTerminalOutcome = "completed" | "bodyless" | "client_cancelled" | "stream_error";
@@ -1790,6 +1868,13 @@ export type ProxyLifecycleEventName = "runtime_sample" | "supervisor_event" | "r
 export type ProxyLifecycleTerminalOutcome = ProxyResponseTerminalOutcome | "handler_error" | "unknown";
 /** Content-free lifecycle event accepted by the bounded metadata logger. */
 export type ProxyLifecycleEventInput = {
+    /** Hard admission-to-terminal deadline used by reconciliation. */
+    requestTimeoutMs?: number;
+    /** Internal adapter requests link to their one client-facing parent. */
+    parentRequestId?: string;
+    accountingScope?: "client" | "internal";
+    /** Exactly this request owns usage; bridge parents never duplicate it. */
+    usageOwnerRequestId?: string;
     event: ProxyLifecycleEventName;
     requestId: string;
     method: string;
@@ -1976,6 +2061,9 @@ export type ProxyAnalysisReport = {
             providerFinalRecorded: boolean;
         }>;
         accepted: number;
+        internalAccepted?: number;
+        internalTerminal?: number;
+        internalUnsettled?: number;
         /** Accepted metadata requests that do not require model final records. */
         auxiliaryRequests: number;
         headers: number;
@@ -1988,6 +2076,8 @@ export type ProxyAnalysisReport = {
     };
     requests: {
         completed: number;
+        /** Linked internal adapter finals excluded from client request totals. */
+        internalCompleted?: number;
         success: number;
         errors: number;
         finalRateLimits: number;
@@ -2075,6 +2165,9 @@ export type ProxyAnalysisAttemptRecord = {
 };
 /** Final request fields retained while joining offline proxy log records. */
 export type ProxyAnalysisFinalRequestRecord = {
+    accountingScope?: "client" | "internal";
+    parentRequestId?: string;
+    usageOwnerRequestId?: string;
     firstUsefulOutputMs: number | null;
     timestamp: string;
     status: number;
@@ -2114,6 +2207,9 @@ export type ProxyCancellableTransformer<I, O> = Transformer<I, O> & {
  * a null result as "not observed", never as "zero tokens".
  */
 export type CodexStreamUsage = {
+    /** Distinguish missing provider usage from a reported zero. */
+    inputTokensObserved?: boolean;
+    outputTokensObserved?: boolean;
     inputTokens: number;
     outputTokens: number;
     cacheReadTokens: number;
@@ -2146,6 +2242,12 @@ export type ProxyAnalysisRoutingRecord = {
 };
 /** Request metadata retained by the HTTP adapter for terminal error logging. */
 export type RuntimeRequestMetadata = {
+    /** Internal adapter requests link to their one client-facing parent. */
+    parentRequestId?: string;
+    accountingScope?: "client" | "internal";
+    /** Exactly this request owns usage; bridge parents never duplicate it. */
+    usageOwnerRequestId?: string;
+    abortController?: AbortController;
     /** Last dispatched attempt, retained until this HTTP request terminates. */
     lastUpstreamAttempt?: RequestAttemptLogEntry;
     requestId: string;
@@ -2331,6 +2433,14 @@ export type CompareProxyReplayOptions = {
 };
 /** Persisted artifact produced when a body is stored to disk. */
 export type StoredBodyArtifact = {
+    /** Bytes supplied to redaction, after any source observer limit. */
+    inputRetainedBytes?: number;
+    inputEncoding?: "utf8_text" | "structured_object";
+    sourceTruncated?: boolean;
+    processingTruncated?: boolean;
+    /** Invalid structured frames were removed for secret safety. */
+    redactionLossy?: boolean;
+    unparseableRedactedFrames?: number;
     bodyPath?: string;
     bodySha256?: string;
     redactedBodyBytes?: number;
@@ -4029,4 +4139,39 @@ type ProxyBodyCaptureWaitingSnapshot = {
     admissionWaits: number;
     admissionTimeouts: number;
 };
+/** Immutable package selection used by the proxy launcher, never by global npm. */
+export type ProxyPackageSelection = {
+    version: string;
+    entryScript: string;
+    nodePath: string;
+};
+/** Atomically published active and rollback package selections. */
+export type ProxyPackageSelectionState = {
+    schemaVersion: 1;
+    active: ProxyPackageSelection | null;
+    previous: ProxyPackageSelection | null;
+};
+/** Bounded asynchronous package installation with injectable subprocesses. */
+export type ProxyStagedInstallOptions = {
+    version: string;
+    packagesDir: string;
+    installer: Pick<GlobalInstallerProbe, "kind" | "bin">;
+    idleTimeoutMs?: number;
+    maxDurationMs?: number;
+    killGraceMs?: number;
+    spawn?: typeof import("node:child_process").spawn;
+    execFileSync?: GlobalInstallerExecFile;
+    onProgress?: (progress: {
+        elapsedMs: number;
+        outputBytes: number;
+    }) => void;
+};
+/** Saved launchd settings retained when installing the service again. */
+export type ProxyServiceInstallSettings = {
+    envFile?: string;
+    configFile?: string;
+    host?: string;
+    port?: number;
+    environment: Record<string, string>;
+};
 export {};

package/dist/types/proxy.js

@@ -1,16 +1 @@
-/**
- * Proxy type definitions for NeuroLink
- *
- * Consolidates all proxy-related types from:
- * - src/lib/proxy/claudeFormat.ts (Claude API types, SSE types, internal result)
- * - src/lib/proxy/cloaking/types.ts (cloaking pipeline types)
- * - src/lib/proxy/cloaking/plugins/ (plugin option types)
- * - src/lib/proxy/modelRouter.ts (routing types)
- * - src/lib/proxy/proxyConfig.ts (config file types)
- * - src/lib/proxy/requestLogger.ts (log entry type)
- * - src/lib/proxy/usageStats.ts (stats types)
- * - src/lib/proxy/tokenRefresh.ts (refresh types)
- * - src/lib/proxy/accountQuota.ts (quota type)
- * - src/lib/server/routes/claudeProxyRoutes.ts (runtime state, deps)
- */
 export {};

package/dist/types/proxyBudget.d.ts

@@ -0,0 +1,74 @@
+/** Operator-configured proxy token caps. All caps are optional and disabled by default. */
+export type ProxyTokenBudgetPolicy = {
+    /** Per-provider/account estimated outstanding input plus maximum output. */
+    maxInFlightTokens?: number;
+    /** Charged tokens in the account's fixed window, including outstanding reservations. */
+    accountWindowTokens?: number;
+    /** Charged tokens across providers/accounts sharing the same client session. */
+    sessionWindowTokens?: number;
+    windowMs?: number;
+};
+export type ProxyTokenBudgetReservation = {
+    provider: string;
+    accountKey: string;
+    sessionKey: string;
+    requestId: string;
+    reservationTokens: number;
+    policy?: ProxyTokenBudgetPolicy;
+    estimateProvenance?: string;
+};
+export type ProxyTokenBudgetSnapshot = {
+    scope: "disabled" | "process" | "supervisor";
+    reservationTokens: number;
+    accountChargedTokens: number;
+    accountInFlightTokens: number;
+    sessionChargedTokens: number;
+    sessionInFlightTokens: number;
+    windowMs: number;
+    estimateProvenance: string;
+    settlement?: "provider_reported" | "estimate_retained" | "cancelled_before_dispatch" | "unconfirmed";
+};
+export type ProxyTokenBudgetLease = {
+    leaseId: string;
+    snapshot: ProxyTokenBudgetSnapshot;
+    settle: (actualTotalTokens?: number) => Promise<void>;
+    cancelBeforeDispatch: () => Promise<void>;
+};
+export type ProxyTokenBudgetBucket = {
+    chargedTokens: number;
+    inFlightTokens: number;
+    startedAt: number;
+    windowMs: number;
+    lastTouched: number;
+};
+export type ProxyTokenBudgetRecord = {
+    owner: string;
+    accountKey: string;
+    sessionKey: string;
+    estimate: number;
+    snapshot: ProxyTokenBudgetSnapshot;
+};
+export type ProxyTokenBudgetRpcRequest = {
+    type: "proxy-budget:request";
+    rpcId: string;
+    pid: number;
+    generation: number;
+    action: "reserve" | "settle" | "cancel";
+    reservation?: ProxyTokenBudgetReservation;
+    leaseId?: string;
+    actualTotalTokens?: number;
+};
+export type ProxyTokenBudgetRpcResponse = {
+    type: "proxy-budget:response";
+    rpcId: string;
+    ok: boolean;
+    leaseId?: string;
+    snapshot?: ProxyTokenBudgetSnapshot;
+    errorCode?: string;
+    error?: string;
+};
+export type ProxyTokenBudgetRpcPending = {
+    resolve: (result: ProxyTokenBudgetRpcResponse) => void;
+    reject: (error: Error) => void;
+    timer: NodeJS.Timeout;
+};

package/dist/types/proxyBudget.js

@@ -0,0 +1 @@
+export {};

package/dist/types/proxyContext.d.ts

@@ -0,0 +1,35 @@
+/** Explicit proxy context controls; all token quantities remain estimates. */
+export type ProxyContextPolicy = {
+    maxInputTokens?: number;
+    outputReserveTokens?: number;
+    enforceDiscoveredLimits?: boolean;
+    toolAllowlist?: string[];
+    models?: Record<string, {
+        contextWindow: number;
+        maxOutputTokens?: number;
+    }>;
+};
+export type ProxyContextEvidence = {
+    provider: string;
+    model: string;
+    inputTokensEstimate: number;
+    toolsTokensEstimate: number;
+    instructionsTokensEstimate: number;
+    schemaTokensEstimate: number;
+    outputTokensReserve: number;
+    reasoningIncludedInOutputReserve: true;
+    contextWindow?: number;
+    contextLimitSource: "configured" | "discovered" | "unknown";
+    tokenCountSource: "estimated";
+    multimodalEstimate: boolean;
+    originalToolCount: number;
+    retainedToolCount: number;
+    historyModified: false;
+};
+export type ProxyPreparedContext<T> = {
+    body: T;
+    inputTokensEstimate: number;
+    outputTokensReserve: number;
+    totalTokensReservation: number;
+    evidence: ProxyContextEvidence;
+};

package/dist/types/proxyContext.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/fileDetector.js

@@ -4,6 +4,7 @@
  * Uses multi-strategy approach for reliable type identification
  */
 import { open, readFile, realpath } from "fs/promises";
+import { STATUS_CODES } from "node:http";
 import { basename, isAbsolute as isAbsolutePath, relative as relativePath, resolve as resolvePath, sep, } from "path";
 import { request } from "undici";
 import { redirectFollowingDispatcher } from "./redirectDispatcher.js";
@@ -675,21 +676,35 @@ export class FileDetector {
             new ContentHeuristicStrategy(),
         ];
         let best = null;
+        // #397: track which strategy produced `best` so the eventual log line
+        // can name it — the strategy instances themselves are gone by the time
+        // logging happens below, only their results survive.
+        let bestStrategyName = "none";
         for (const strategy of strategies) {
+            const strategyName = strategy.constructor.name;
             const result = await strategy.detect(strategy instanceof ExtensionStrategy && extensionInput
                 ? extensionInput
                 : input);
             if (!best || result.metadata.confidence > best.metadata.confidence) {
                 best = result;
+                bestStrategyName = strategyName;
             }
             if (result.metadata.confidence >= confidenceThreshold) {
-                logger.info(`[FileDetector] Type: ${result.type} (${result.metadata.confidence}%)`);
+                logger.info(`[FileDetector] Type: ${result.type} (${result.metadata.confidence}%, strategy: ${strategyName})`);
                 return FileDetector.withResolvedExtension(result, input, options);
             }
         }
-        // Below-threshold detection is the common case for any file under the
-        // ContentHeuristic ceiling — a debug detail, not a warning-worthy anomaly.
-        logger.debug(`[FileDetector] Best-effort type below threshold: ${best?.type ?? "unknown"} (${best?.metadata.confidence ?? 0}%, threshold ${confidenceThreshold}%)`);
+        // A genuinely unidentifiable input — every strategy failed to produce
+        // even a type — is a real failure, not a best-effort guess, so it is
+        // surfaced at error level instead of being buried in debug output.
+        if (!best || best.type === "unknown") {
+            logger.error(`[FileDetector] Detection failed: no strategy identified a type (best: ${bestStrategyName}, ${best?.metadata.confidence ?? 0}%, threshold ${confidenceThreshold}%)`);
+        }
+        else {
+            // Below-threshold detection is the common case for any file under the
+            // ContentHeuristic ceiling — a debug detail, not a warning-worthy anomaly.
+            logger.debug(`[FileDetector] Best-effort type below threshold: ${best.type} (${best.metadata.confidence}%, threshold ${confidenceThreshold}%, strategy: ${bestStrategyName})`);
+        }
         return FileDetector.withResolvedExtension(best, input, options);
     }
     /**
@@ -1543,9 +1558,15 @@ export class FileDetector {
                     bodyTimeout: timeout,
                 });
                 if (response.statusCode !== 200) {
-                    // Query string / fragment stripped — a presigned URL's token must
-                    // not be echoed into a thrown error.
-                    throw new Error(`HTTP ${response.statusCode} fetching ${redactUrlForError(url)}`);
+                    // #360: pair the code with its standard reason phrase (e.g. 404 →
+                    // "Not Found") so the message is readable rather than a bare
+                    // number. Sourced from Node's own `http.STATUS_CODES` table
+                    // rather than a hand-written map that could drift from it, and
+                    // falls back gracefully for a non-standard code that table
+                    // doesn't recognize. Query string / fragment stays stripped — a
+                    // presigned URL's token must not be echoed into a thrown error.
+                    const statusText = STATUS_CODES[response.statusCode];
+                    throw new Error(`HTTP ${response.statusCode}${statusText ? ` ${statusText}` : ""} fetching ${redactUrlForError(url)}`);
                 }
                 const contentType = response.headers["content-type"] || "";
                 const declaredLength = Number(response.headers["content-length"]);

package/dist/utils/messageBuilder.js

@@ -1877,10 +1877,14 @@ async function processImageToBase64(image, index) {
             const match = image.match(/^data:([^;]+);base64,(.+)$/);
             if (match) {
                 const declaredMime = match[1];
-                // #348: only accept image/* data URIs; reject a non-image MIME before
-                // it reaches a provider API rather than passing it through unchecked.
-                if (!declaredMime.startsWith("image/")) {
-                    throw new Error(`Unsupported data URI MIME type for image input at index ${index}: "${declaredMime}" (expected image/*)`);
+                // #348: validate against the actual supported-image allowlist, not
+                // just the "image/*" prefix — "image/invalid-format" started with
+                // "image/" and passed here, only to fail later at the provider.
+                // Reuses ImageProcessor's allowlist (itself sourced from
+                // imageFormatSupport's SUPPORTED_INPUT_IMAGE_MIME_TYPES) so intake
+                // validation can never drift from the set NeuroLink actually accepts.
+                if (!ImageProcessor.validateImageFormat(declaredMime)) {
+                    throw new Error(`Unsupported data URI MIME type for image input at index ${index}: "${declaredMime}" (not a supported image format)`);
                 }
                 mimeType = declaredMime;
                 imageData = match[2]; // Raw base64 only — NOT the full data: URI
@@ -2323,7 +2327,16 @@ pdfFiles, provider, model, audioFiles = []) {
             for (const pdf of pdfFiles) {
                 try {
                     const effectiveMaxPages = pdf.maxPages ?? PDF_LIMITS.DEFAULT_MAX_PAGES;
-                    const conversionResult = await PDFImageConverter.convertToImages(pdf.buffer, {
+                    // #302: stream pages one at a time instead of materialising every
+                    // rendered page before any of them reaches `content` — this is the
+                    // path generate()/stream() callers actually exercise, so it must
+                    // carry the memory characteristic convertToImagesStream was built
+                    // for. Per-page ordering, error isolation (#294) and the resulting
+                    // message content are kept identical to the batch path below;
+                    // only how the pages are produced changes.
+                    const pageErrors = [];
+                    let convertedCount = 0;
+                    for await (const page of PDFImageConverter.convertToImagesStream(pdf.buffer, {
                         // #297: this is the only PDF→image call the product actually makes,
                         // and it used to hardcode scale 2.0 — silently overriding the
                         // lowered PDF_LIMITS.DEFAULT_SCALE and keeping the memory cost the
@@ -2337,7 +2350,34 @@ pdfFiles, provider, model, audioFiles = []) {
                         ...(pdf.maxCanvasPixels
                             ? { maxCanvasPixels: pdf.maxCanvasPixels }
                             : {}), // #260
-                    });
+                    })) {
+                        if (page.error) {
+                            // #294: per-page isolation — a failed page is recorded and
+                            // skipped, not thrown, so the rest of the document still
+                            // reaches the model.
+                            pageErrors.push({ page: page.pageIndex, error: page.error });
+                            continue;
+                        }
+                        convertedCount++;
+                        // Add each page as an ImagePart (raw base64, not data: URI — see SSRF note above)
+                        content.push({
+                            type: "image",
+                            image: page.image,
+                            mimeType: "image/png",
+                        });
+                        logger.debug(`[PDF→Image] Added page ${page.pageIndex} of ${pdf.filename}`);
+                    }
+                    // Batch's convertToImages throws when nothing converted (either a
+                    // zero-page PDF or every page failed) instead of returning an empty
+                    // result; convertToImagesStream has no such guard (it simply yields
+                    // nothing / all-error pages), so replicate that contract explicitly
+                    // to keep the two paths' failure behavior identical.
+                    if (convertedCount === 0) {
+                        if (pageErrors.length > 0) {
+                            throw new Error(`All ${pageErrors.length} page(s) failed to render. First error: ${pageErrors[0].error}`);
+                        }
+                        throw new Error("PDF has 0 pages. Cannot convert empty PDF to images.");
+                    }
                     // The renderer stops at maxPages, so a longer document is silently
                     // truncated — say so rather than letting the model answer from a
                     // partial document as though it had the whole thing.
@@ -2348,31 +2388,16 @@ pdfFiles, provider, model, audioFiles = []) {
                     // there. Reaching the cap is also unambiguous — a short count caused by
                     // per-page render failures (#294 isolates those into `errors`) would
                     // otherwise be misreported as a maxPages truncation.
-                    if (conversionResult.pageCount >= effectiveMaxPages) {
+                    if (convertedCount >= effectiveMaxPages) {
                         logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)} hit the ${effectiveMaxPages}-page ` +
                             `conversion limit. Any pages beyond that were not sent — the model may be ` +
                             `answering from a partial document. Raise pdfOptions.maxPages or split the file.`);
                     }
-                    if (conversionResult.errors && conversionResult.errors.length > 0) {
-                        logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)}: ${conversionResult.errors.length} page(s) ` +
-                            `failed to render and were omitted (page ${conversionResult.errors.map((e) => e.page).join(", ")}).`);
-                    }
-                    logger.info(`[PDF→Image] ✅ Converted ${pdf.filename}: ${conversionResult.pageCount} page(s) → images`);
-                    // Add each page as an ImagePart (raw base64, not data: URI — see SSRF note above)
-                    conversionResult.images.forEach((base64Image, pageIndex) => {
-                        content.push({
-                            type: "image",
-                            image: base64Image,
-                            mimeType: "image/png",
-                        });
-                        logger.debug(`[PDF→Image] Added page ${pageIndex + 1}/${conversionResult.pageCount} of ${pdf.filename}`);
-                    });
-                    // Log any warnings from conversion
-                    if (conversionResult.warnings) {
-                        conversionResult.warnings.forEach((warning) => {
-                            logger.warn(`[PDF→Image] ${warning}`);
-                        });
+                    if (pageErrors.length > 0) {
+                        logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)}: ${pageErrors.length} page(s) ` +
+                            `failed to render and were omitted (page ${pageErrors.map((e) => e.page).join(", ")}).`);
                     }
+                    logger.info(`[PDF→Image] ✅ Converted ${pdf.filename}: ${convertedCount} page(s) → images`);
                 }
                 catch (error) {
                     const errorMessage = error instanceof Error ? error.message : String(error);