@nanogpt/private-mode 0.2.9 → 0.2.13

package/README.md

@@ -5,7 +5,7 @@ OpenAI-compatible localhost proxy for NanoGPT Private Mode with supported TEE mo
 Requires Node.js 22 or later.
 
 ```bash
-NANOGPT_API_KEY=sk-your-key npx @nanogpt/private-mode
+NANOGPT_API_KEY=sk-your-key npx --yes @nanogpt/private-mode@latest
 ```
 
 Then point any OpenAI-compatible client at:
@@ -32,18 +32,32 @@ const response = await client.chat.completions.create({
 
 The local proxy verifies TEE attestation, encrypts request bodies with EHBP, sends ciphertext through NanoGPT, decrypts encrypted responses locally, and returns normal OpenAI JSON to the calling app.
 
+The model list is bundled with the installed proxy package. Before the proxy starts listening, it checks that list against NanoGPT's hosted Private Mode catalog and stops with an upgrade command if models were added or retired. This prevents an old package from advertising enclave targets that are no longer available. The running proxy reports its exact version at `GET http://127.0.0.1:8787/v1/private-mode/status`. To print the latest published package version, run:
+
+```bash
+npx --yes @nanogpt/private-mode@latest --version
+```
+
+If an older proxy is already running, stop it before starting the command above. API clients must use the localhost base URL shown below; sending `private/*` model IDs directly to NanoGPT's standard `/api/v1/chat/completions` endpoint does not enable Private Mode.
+
 After a long idle period (five minutes by default), the proxy re-verifies attestation and creates a fresh encrypted transport before the next request. This makes laptop sleep/resume safe without requiring a proxy restart. Set `NANOGPT_PRIVATE_CLIENT_IDLE_RESET_MS` to a positive millisecond value to adjust the idle threshold, or `0` to disable idle resets.
 
 NanoGPT can see account identity, selected private model, selected TEE target metadata, timing, sizes, status, and usage metadata. NanoGPT cannot read the prompt or completion body for supported private models.
 
 NanoGPT's web app can also use these models without running this local proxy. Select an eligible Private Mode model and use the Private Mode control in the model picker. This package is for API clients, CLIs, agents, and other OpenAI-compatible tools.
 
-The web-app toggle is narrower than the proxy path in v1. It supports text chat and model settings, and disables attachments, web search, URL-scraped content, project tools, multi-model chat, Context Memory injection, quick replies, and automatic title generation for private turns.
+The web app supports local image attachments for Private Mode vision models (Kimi K3 and Gemma 4 31B). Image bytes are converted to base64 in the browser and included inside the EHBP-encrypted request; they are not uploaded to NanoGPT object storage. Other attachment types, web search, URL-scraped content, project tools, multi-model chat, Context Memory injection, quick replies, and automatic title generation remain disabled for private turns.
 
 In the hosted web app, decrypted Private Mode turns remain in local browser history. Cloud conversation sync is blocked for Private Mode chats unless password-based end-to-end sync is enabled; the recoverable default sync mode is not used for those chats.
 
 Private Mode also requires enough NanoGPT balance and API-key spend-limit headroom before dispatch. For streaming calls, NanoGPT may precharge a conservative reserve before dispatch and refund unused balance after verified usage metadata is available.
 
+Because the request body is encrypted before NanoGPT receives it, the service cannot inspect the request's `max_tokens` value during the balance precheck. The default streaming reserve therefore includes up to 32,768 output tokens, even when the encrypted request asks for fewer. This is a temporary reserve, not the final charge: unused balance is refunded when verified usage metadata arrives. The encrypted `max_tokens` value still controls generation inside the verified TEE.
+
+Private Mode streaming has a 29-minute soft deadline so billing can settle before the route's 30-minute hard runtime limit. If the decrypted upstream stream ends without both a non-null `finish_reason` and the OpenAI `[DONE]` marker, the local proxy emits an SSE error with code `private_stream_incomplete`. Any text received before that error may be partial.
+
+Private Mode currently supports Chat Completions only. The Responses API and Batch API are not available through the encrypted Private Mode endpoint. The standard Responses API outside Private Mode supports background requests within its configured 30-minute runtime limit; work that must reliably continue longer needs a durable job system.
+
 Useful local checks:
 
 ```text
@@ -54,17 +68,23 @@ GET http://127.0.0.1:8787/v1/private-mode/attestation
 
 Supported private model IDs include:
 
-- `private/deepseek-v4-flash`
+- `private/deepseek-v4-flash` - DeepSeek V4 Flash 0731
 - `private/kimi-k3`
-- `private/glm-5-1`
-- `private/glm-5-1-thinking`
+- `private/gpt-oss-120b`
+- `private/llama3-3-70b`
 - `private/glm-5-2`
 - `private/glm-5-2:thinking`
+- `private/glm-5-3`
+- `private/glm-5-3-flash`
+- `private/gemma4-31b`
+- `private/gemma4-31b:thinking`
+
+Both GLM 5.2 variants are deployed with a 393,216-token total context limit, with prompt and output sharing that window. GLM 5.3 Private and GLM 5.3 Flash Private each have a 1,048,576-token total context limit and a 131,072-token output ceiling. Kimi K3 Private has a 256,000-token context limit. DeepSeek V4 Flash 0731 Private has a 1,048,576-token total context limit. The model-list extension `context_length` is the combined prompt-and-output window, while `max_output_tokens` is the output ceiling within that same window. These values are not additive.
 
 Browser requests are locked down by default. The proxy only accepts same-machine clients and rejects browser `Origin` headers that are not explicitly allowed, so a random website or LAN client cannot spend the local `NANOGPT_API_KEY` while the proxy is running. If a local browser app needs to call the proxy directly, allow that exact origin:
 
 ```bash
-NANOGPT_API_KEY=sk-your-key npx @nanogpt/private-mode --allow-origin http://localhost:3000
+NANOGPT_API_KEY=sk-your-key npx --yes @nanogpt/private-mode@latest --allow-origin http://localhost:3000
 ```
 
 You can also set `NANOGPT_PRIVATE_ALLOWED_ORIGINS=http://localhost:3000`. Wildcard browser origins are not supported.
@@ -86,13 +106,13 @@ NanoGPT's hosted web app shows a Private Mode receipt on completed Private Mode
 To independently verify a copied receipt:
 
 ```bash
-npx @nanogpt/private-mode verify receipt.json
+npx --yes @nanogpt/private-mode@latest verify receipt.json
 ```
 
 You can also pipe JSON on stdin:
 
 ```bash
-cat receipt.json | npx @nanogpt/private-mode verify
+cat receipt.json | npx --yes @nanogpt/private-mode@latest verify
 ```
 
 The verifier re-fetches attestation material for the receipt's enclave, verifies it locally, and checks the resulting measurements, release digest, and HPKE key against the copied receipt. If an optional attestation bundle hash is present but the freshly fetched bundle serializes differently, the verifier prints a warning instead of failing the core verification.

package/bin/nanogpt-private-mode.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 import { parseArgs } from 'node:util';
+import { PRIVATE_MODE_PROXY_VERSION } from '../lib/packageInfo.js';
 import { startPrivateModeProxy } from '../lib/server.js';
 import { verifyPrivateModeReceiptCli } from '../lib/verifyReceipt.js';
 
@@ -14,10 +15,16 @@ const { values, positionals } = parseArgs({
     },
     'allow-origin': { type: 'string', multiple: true },
     help: { type: 'boolean', short: 'h', default: false },
+    version: { type: 'boolean', short: 'v', default: false },
   },
   allowPositionals: true,
 });
 
+if (values.version) {
+  process.stdout.write(`${PRIVATE_MODE_PROXY_VERSION}\n`);
+  process.exit(0);
+}
+
 if (values.help) {
   process.stdout.write(`NanoGPT Private Mode Proxy
 
@@ -32,6 +39,7 @@ Options:
   --api-base <url>    NanoGPT API base. Default: https://nano-gpt.com
   --allow-origin <origin>
                      Browser origin allowed to call the proxy, for example http://localhost:3000
+  --version, -v      Print the installed proxy version
 `);
   process.exit(0);
 }

package/lib/catalogCompatibility.js

@@ -0,0 +1,76 @@
+const DEFAULT_CATALOG_CHECK_TIMEOUT_MS = 10_000;
+
+function normalizeModelIds(models) {
+  if (!Array.isArray(models)) return null;
+
+  const ids = models.map((model) => (
+    typeof model?.id === 'string' ? model.id.trim().toLowerCase() : ''
+  ));
+  if (ids.some((id) => !id)) return null;
+
+  return new Set(ids);
+}
+
+export function comparePrivateModeCatalogs(localModels, hostedCatalog) {
+  const localIds = normalizeModelIds(localModels);
+  const hostedIds = normalizeModelIds(hostedCatalog?.data);
+  if (!localIds || !hostedIds) {
+    throw new Error('Private Mode model catalog response was malformed.');
+  }
+
+  return {
+    status: 'checked',
+    retiredLocalModels: [...localIds].filter((id) => !hostedIds.has(id)).sort(),
+    missingLocalModels: [...hostedIds].filter((id) => !localIds.has(id)).sort(),
+  };
+}
+
+export async function checkHostedPrivateModeCatalog({
+  apiBase,
+  localModels,
+  fetchImpl = fetch,
+  timeoutMs = DEFAULT_CATALOG_CHECK_TIMEOUT_MS,
+}) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetchImpl(`${apiBase}/api/v1/private/tinfoil/models`, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      return { status: 'unavailable', reason: `HTTP ${response.status}` };
+    }
+
+    return comparePrivateModeCatalogs(localModels, await response.json());
+  } catch (error) {
+    return {
+      status: 'unavailable',
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function hasPrivateModeCatalogMismatch(result) {
+  return result.status === 'checked'
+    && (result.retiredLocalModels.length > 0 || result.missingLocalModels.length > 0);
+}
+
+export function buildPrivateModeCatalogUnavailableMessage(result, apiBase) {
+  return `Could not verify the bundled Private Mode model catalog against ${apiBase}: ${result.reason}. The proxy did not start because catalog compatibility could not be confirmed. Check your network connection and NanoGPT service availability, then retry.`;
+}
+
+export function buildPrivateModeCatalogMismatchMessage(result, proxyVersion) {
+  const details = [];
+  if (result.retiredLocalModels.length > 0) {
+    details.push(`retired local models: ${result.retiredLocalModels.join(', ')}`);
+  }
+  if (result.missingLocalModels.length > 0) {
+    details.push(`hosted models missing locally: ${result.missingLocalModels.join(', ')}`);
+  }
+
+  return `The bundled Private Mode model catalog in @nanogpt/private-mode v${proxyVersion} is out of date (${details.join('; ')}). Stop this proxy and restart with: NANOGPT_API_KEY=... npx --yes @nanogpt/private-mode@latest`;
+}

package/lib/constants.js

@@ -0,0 +1,6 @@
+export const PRIVATE_MODE_STREAM_ROUTE_MAX_DURATION_MS = 30 * 60 * 1000;
+export const PRIVATE_MODE_STREAM_SOFT_DEADLINE_LEAD_MS = 60 * 1000;
+export const PRIVATE_MODE_STREAM_SETTLEMENT_SAFETY_MS = 30 * 1000;
+export const PRIVATE_MODE_STREAM_SOFT_DEADLINE_MS =
+  PRIVATE_MODE_STREAM_ROUTE_MAX_DURATION_MS - PRIVATE_MODE_STREAM_SOFT_DEADLINE_LEAD_MS;
+export const PRIVATE_MODE_DEFAULT_RESERVE_MAX_OUTPUT_TOKENS = 32_768;

package/lib/packageInfo.js

@@ -0,0 +1,8 @@
+import { readFileSync } from 'node:fs';
+
+const packageJson = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+);
+
+export const PRIVATE_MODE_PROXY_VERSION = String(packageJson.version);
+export const PRIVATE_MODE_PROXY_VERSION_HEADER = 'x-nanogpt-private-proxy-version';

package/lib/requestTransforms.js

@@ -29,6 +29,7 @@ const KIMI_K3_TEXT_ENCODER = new TextEncoder();
 const DEEPSEEK_V4_CONTEXT_WINDOW_TOKENS = 1_048_576;
 const DEEPSEEK_V4_MAX_COMPLETION_TOKENS = 1_048_576;
 const DEEPSEEK_V4_CONTEXT_SAFETY_MARGIN_TOKENS = 10;
+const GLM_53_MAX_COMPLETION_TOKENS = 131_072;
 const PRIVATE_TINFOIL_CHAT_COMPLETION_BODY_FIELDS = new Set([
   'chat_template_kwargs',
   'frequency_penalty',
@@ -243,6 +244,14 @@ function normalizeDeepSeekV4ReasoningEffort(value) {
   return 'high';
 }
 
+function normalizeGlm53ReasoningEffort(value) {
+  const normalized = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (normalized === 'max' || normalized === 'xhigh') return 'max';
+  if (normalized === 'low' || normalized === 'minimal') return 'low';
+  if (normalized === 'high' || normalized === 'medium') return 'high';
+  return 'max';
+}
+
 function getPrivateModeModelSignals(body, model) {
   return [
     body.model,
@@ -419,6 +428,10 @@ function isPrivateModeKimiK3Model(model) {
     });
 }
 
+function isPrivateModeGlm53Model(model) {
+  return model.thinkingMode === 'glm-5.3';
+}
+
 function getPrivateModeFunctionToolName(tool) {
   if (!isPlainObject(tool) || tool.type !== 'function' || !isPlainObject(tool.function)) {
     return undefined;
@@ -513,7 +526,7 @@ export function normalizePrivateModelReasoningControls(body, model) {
 
 export function shouldSuppressPrivateModelReasoning(body, model) {
   const isKimiK3 = isPrivateModeKimiK3Model(model);
-  if (!isKimiK3 && model.thinkingMode !== 'deepseek-v4') return false;
+  if (!isKimiK3 && model.thinkingMode !== 'deepseek-v4' && model.thinkingMode !== 'glm-5.3') return false;
   const reasoningVisibilityOptOut = body.reasoningOptOut === true ||
     body.exposeReasoning === false ||
     body.materializeReasoning === false ||
@@ -528,9 +541,6 @@ export function shouldSuppressPrivateModelReasoning(body, model) {
 
 function resolvePrivateModeKimiK3ReasoningEffort(body) {
   const candidates = [
-    body.reasoningOptOut === true ? false : undefined,
-    body.exposeReasoning === false ? false : undefined,
-    body.materializeReasoning === false ? false : undefined,
     body.enable_thinking,
     body.thinking,
     body.reasoning_effort,
@@ -544,8 +554,7 @@ function resolvePrivateModeKimiK3ReasoningEffort(body) {
   const normalizedEffort = typeof explicitEffort === 'string'
     ? explicitEffort.trim().toLowerCase()
     : undefined;
-  const excludesReasoning = candidates.some((value) => isPlainObject(value) && value.exclude === true);
-  return excludesReasoning ? normalizedEffort ?? 'low' : normalizedEffort ?? 'max';
+  return normalizedEffort ?? 'max';
 }
 
 function applyPrivateModeKimiK3RequestParams(body, model) {
@@ -618,6 +627,20 @@ function clampPrivateModeDeepSeekV4Output(body) {
   );
 }
 
+function clampPrivateModeGlm53Output(body) {
+  const requested = typeof body.max_tokens === 'number' && Number.isFinite(body.max_tokens)
+    ? body.max_tokens
+    : undefined;
+  if (requested === undefined) return;
+  const promptTokens = estimatePrivateModeKimiK3PromptTokens(body);
+  const remainingContext = Math.max(1, DEEPSEEK_V4_CONTEXT_WINDOW_TOKENS - promptTokens - DEEPSEEK_V4_CONTEXT_SAFETY_MARGIN_TOKENS);
+  body.max_tokens = Math.min(
+    requested < 0 ? GLM_53_MAX_COMPLETION_TOKENS : Math.max(1, Math.floor(requested)),
+    GLM_53_MAX_COMPLETION_TOKENS,
+    remainingContext,
+  );
+}
+
 export function createPrivateModeReasoningContentSuppressor() {
   const openTags = ['<think>', '<thinking>', '<previous_reasoning>', '◁think▷'];
   const closeTags = ['</think>', '</thinking>', '</previous_reasoning>', '◁/think▷'];
@@ -679,13 +702,128 @@ export function createPrivateModeReasoningContentSuppressor() {
 }
 
 export function splitCompleteSseFrames(buffer) {
-  const parts = buffer.split(/\r?\n\r?\n/);
+  const parts = buffer.split(/(?:\r\n|\r|\n){2}/);
   return {
-    frames: parts.slice(0, -1).map((frame) => frame.replace(/\r\n/g, '\n')),
+    frames: parts.slice(0, -1).map((frame) => frame.replace(/\r\n|\r/g, '\n')),
     remainder: parts.at(-1) || '',
   };
 }
 
+export function createPrivateModeSseTerminalState(expectedChoiceCount = 1) {
+  return {
+    expectedChoiceCount: Number.isSafeInteger(expectedChoiceCount) && expectedChoiceCount > 0
+      ? expectedChoiceCount
+      : 1,
+    finishedChoiceIndexes: new Set(),
+    sawDone: false,
+  };
+}
+
+function readPrivateModeSseDataPayload(frame) {
+  if (typeof frame !== 'string') return '';
+  return frame
+    .split('\n')
+    .filter((line) => line.startsWith('data:'))
+    .map((line) => line.slice('data:'.length).trim())
+    .join('\n')
+    .trim();
+}
+
+export function observePrivateModeSseTerminalFrame(state, frame) {
+  if (!isPlainObject(state) || typeof frame !== 'string') return state;
+  const payload = readPrivateModeSseDataPayload(frame);
+  if (!payload) return state;
+  if (payload === '[DONE]') {
+    state.sawDone = true;
+    return state;
+  }
+
+  try {
+    const parsed = JSON.parse(payload);
+    if (isPlainObject(parsed) && Array.isArray(parsed.choices)) {
+      for (const choice of parsed.choices) {
+        if (
+          !isPlainObject(choice) ||
+          choice.finish_reason === undefined ||
+          choice.finish_reason === null
+        ) continue;
+        const choiceIndex = Number.isSafeInteger(choice.index)
+          ? choice.index
+          : state.expectedChoiceCount === 1
+            ? 0
+            : null;
+        if (choiceIndex !== null && choiceIndex >= 0 && choiceIndex < state.expectedChoiceCount) {
+          state.finishedChoiceIndexes.add(choiceIndex);
+        }
+      }
+    }
+  } catch {
+    // Other SSE payloads do not contribute to the OpenAI terminal sequence.
+  }
+  return state;
+}
+
+export function isPrivateModeSseTerminalStateComplete(state) {
+  return state?.sawDone === true &&
+    state?.finishedChoiceIndexes instanceof Set &&
+    state.finishedChoiceIndexes.size === state.expectedChoiceCount;
+}
+
+export function createPrivateModeSseTerminalGuard(expectedChoiceCount = 1) {
+  const state = createPrivateModeSseTerminalState(expectedChoiceCount);
+  let emittedDone = false;
+  return {
+    state,
+    observe(frame, forwardedFrame = frame) {
+      const doneAlreadyEmitted = emittedDone;
+      const containsDone = readPrivateModeSseDataPayload(frame) === '[DONE]';
+      observePrivateModeSseTerminalFrame(state, frame);
+      // The pump drains transport bytes after client-visible completion so the
+      // hosted request can finish settlement. Nothing from that drain belongs
+      // on the client side of the canonical terminal marker.
+      if (doneAlreadyEmitted) return '';
+      // Drop every raw DONE marker so duplicates collapse to one canonical
+      // marker. Reasoning suppression may prepend a synthetic visible-content
+      // delta, which must remain ahead of that marker.
+      const forwardedWithoutDone = containsDone
+        ? forwardedFrame
+          .split(/(?:\r\n|\r|\n){2}/)
+          .filter((forwarded) => readPrivateModeSseDataPayload(forwarded) !== '[DONE]')
+          .join('\n\n')
+        : forwardedFrame;
+
+      // A hosted stream can keep transport EOF open while billing settles.
+      // Release successful completion as soon as the full SSE terminal
+      // sequence is observed, then let the response pump drain the transport.
+      if (!emittedDone && isPrivateModeSseTerminalStateComplete(state)) {
+        emittedDone = true;
+        return [forwardedWithoutDone, 'data: [DONE]'].filter(Boolean).join('\n\n');
+      }
+      return forwardedWithoutDone;
+    },
+    hasEmittedDone() {
+      return emittedDone;
+    },
+    finish() {
+      if (isPrivateModeSseTerminalStateComplete(state)) {
+        if (emittedDone) return { complete: true, frame: '' };
+        emittedDone = true;
+        return { complete: true, frame: 'data: [DONE]' };
+      }
+      return {
+        complete: false,
+        frame: `data: ${JSON.stringify({
+          error: {
+            message: 'Private Mode stream ended before a complete terminal sequence. The response may be partial; retry the request.',
+            type: 'api_error',
+            code: 'private_stream_incomplete',
+          },
+        })}`,
+      };
+    },
+  };
+}
+
 const PRIVATE_MODE_SSE_CHUNK_METADATA_FIELDS = [
   'id',
   'object',
@@ -896,10 +1034,12 @@ function normalizeStreamOptions(body) {
 }
 
 export function applyPrivateModelRequestMutations(body, model) {
-  if (isPrivateModeKimiK3Model(model)) {
+  if (isPrivateModeKimiK3Model(model) || isPrivateModeGlm53Model(model)) {
     normalizePrivateModelReasoningControls(body, model);
     normalizePrivateModeKimiK3ReasoningFromMessages(body);
-    normalizePrivateModeKimiK3DynamicToolMessages(body);
+    if (isPrivateModeKimiK3Model(model)) {
+      normalizePrivateModeKimiK3DynamicToolMessages(body);
+    }
   } else {
     stripPrivateModeReasoningFromMessages(body);
   }
@@ -911,6 +1051,8 @@ export function applyPrivateModelRequestMutations(body, model) {
     applyPrivateModeKimiK3RequestParams(body, model);
   } else if (model.thinkingMode === 'deepseek-v4') {
     clampPrivateModeDeepSeekV4Output(body);
+  } else if (model.thinkingMode === 'glm-5.3') {
+    clampPrivateModeGlm53Output(body);
   }
 
   if (model.thinkingMode === 'gemma') {
@@ -922,9 +1064,12 @@ export function applyPrivateModelRequestMutations(body, model) {
     delete body.reasoning_effort;
   } else if (
     model.thinkingMode === 'glm-5.2' ||
+    model.thinkingMode === 'glm-5.3' ||
     model.thinkingMode === 'deepseek-v4'
   ) {
-    const thinkingEnabled = shouldEnableThinking(body, model);
+    const thinkingEnabled = model.thinkingMode === 'glm-5.3'
+      ? true
+      : shouldEnableThinking(body, model);
     const requestedReasoningEffort = body.reasoning_effort
       ?? (isPlainObject(body.reasoning) ? body.reasoning.effort : undefined);
     body.chat_template_kwargs = {
@@ -933,8 +1078,9 @@ export function applyPrivateModelRequestMutations(body, model) {
     };
 
     if (thinkingEnabled) {
-      body.chat_template_kwargs.reasoning_effort =
-        normalizeDeepSeekV4ReasoningEffort(requestedReasoningEffort);
+      body.chat_template_kwargs.reasoning_effort = model.thinkingMode === 'glm-5.3'
+        ? normalizeGlm53ReasoningEffort(requestedReasoningEffort)
+        : normalizeDeepSeekV4ReasoningEffort(requestedReasoningEffort);
     } else {
       delete body.chat_template_kwargs.reasoning_effort;
     }

package/lib/server.js

@@ -2,23 +2,33 @@ import { createServer } from 'node:http';
 import { readFileSync } from 'node:fs';
 
 import { buildPrivateModeCacheScopeProof } from './cacheScope.js';
+import {
+  buildPrivateModeCatalogMismatchMessage,
+  buildPrivateModeCatalogUnavailableMessage,
+  checkHostedPrivateModeCatalog,
+  hasPrivateModeCatalogMismatch,
+} from './catalogCompatibility.js';
+import {
+  PRIVATE_MODE_DEFAULT_RESERVE_MAX_OUTPUT_TOKENS,
+  PRIVATE_MODE_STREAM_SOFT_DEADLINE_MS,
+} from './constants.js';
 import {
   buildPrivateModeOriginPolicy,
   getCorsHeadersForRequest,
 } from './originPolicy.js';
 import {
   applyPrivateModelRequestMutations,
-  buildPrivateModeSseContentDelta,
-  createPrivateModeReasoningContentSuppressor,
   shouldSuppressPrivateModelReasoning,
-  splitCompleteSseFrames,
-  suppressPrivateModeReasoningFromSseFrame,
   suppressPrivateModeReasoningFromJsonText,
 } from './requestTransforms.js';
 import {
   normalizePrivateModeUpstreamErrorMessage,
   readErrorMessage,
 } from './serverErrorNormalization.js';
+import {
+  PRIVATE_MODE_PROXY_VERSION,
+  PRIVATE_MODE_PROXY_VERSION_HEADER,
+} from './packageInfo.js';
 import {
   createSecureState,
   fetchWithSecureClientRecovery,
@@ -27,6 +37,10 @@ import {
   buildPrivateModeStatusContract,
   buildPublicAttestationSummary,
 } from './statusContract.js';
+import {
+  isPrivateModeSseResponse,
+  pipePrivateModeSseResponse,
+} from './sseResponsePump.js';
 
 const MODELS = JSON.parse(
   readFileSync(new URL('../models/private-tee.json', import.meta.url), 'utf8'),
@@ -79,16 +93,18 @@ function openAIModelList() {
       object: 'model',
       created: model.created,
       owned_by: model.ownedBy,
+      ...(model.maxInputTokens ? { context_length: model.maxInputTokens } : {}),
       ...(model.maxOutputTokens ? { max_output_tokens: model.maxOutputTokens } : {}),
     })),
   };
 }
 
-export function privateModeStatus(apiBase, secureState, localBase, originPolicy) {
+export function privateModeStatus(apiBase, secureState, localBase, originPolicy, catalogCompatibility) {
   const verificationState = secureState.getVerificationState();
   return {
     ok: true,
     mode: 'private_tee',
+    proxy_version: PRIVATE_MODE_PROXY_VERSION,
     apiBase,
     local_base_url: localBase,
     models_path: '/v1/models',
@@ -101,11 +117,18 @@ export function privateModeStatus(apiBase, secureState, localBase, originPolicy)
     response_body_encrypted: true,
     streaming: true,
     streaming_billing: 'precharged_reserve_with_verified_usage_refund',
+    // This deadline is enforced by the hosted route, not this process. A
+    // local environment override cannot configure the remote service.
+    streaming_soft_deadline_ms: PRIVATE_MODE_STREAM_SOFT_DEADLINE_MS,
+    default_stream_reserve_max_output_tokens: PRIVATE_MODE_DEFAULT_RESERVE_MAX_OUTPUT_TOKENS,
+    responses_api_supported: false,
+    batch_api_supported: false,
     api_local_proxy_required: true,
     browser_frontend_local_proxy_required: false,
     ...buildPrivateModeStatusContract(verificationState),
     browser_origins_allowed: originPolicy.allowedOrigins,
     models: openAIModelList().data,
+    catalog_compatibility: catalogCompatibility,
     attestation: buildPublicAttestationSummary(verificationState),
   };
 }
@@ -178,6 +201,7 @@ async function runPreflight({ apiBase, apiKey, model, req, requestBodyBytes }) {
     headers: {
       authorization: `Bearer ${apiKey}`,
       'content-type': 'application/json',
+      [PRIVATE_MODE_PROXY_VERSION_HEADER]: PRIVATE_MODE_PROXY_VERSION,
       ...copyLocalHeaders(req),
     },
     body: JSON.stringify(preflightBody),
@@ -269,7 +293,7 @@ async function handleChatCompletion({ apiBase, apiKey, secureState, req, res, co
   if (!model) {
     jsonResponse(res, 400, {
       error: {
-        message: `Unsupported private model "${body.model || ''}".`,
+        message: `Unsupported private model "${body.model || ''}" in @nanogpt/private-mode v${PRIVATE_MODE_PROXY_VERSION}. Check this proxy's /v1/models endpoint or restart with: NANOGPT_API_KEY=... npx --yes @nanogpt/private-mode@latest`,
         type: 'invalid_request_error',
         code: 'model_not_supported',
       },
@@ -280,6 +304,7 @@ async function handleChatCompletion({ apiBase, apiKey, secureState, req, res, co
   const suppressReasoning = shouldSuppressPrivateModelReasoning(body, model);
   applyPrivateModelRequestMutations(body, model);
   const privateStreamRequested = body.stream === true;
+  const expectedChoiceCount = Number.isSafeInteger(body.n) && body.n > 0 ? body.n : 1;
 
   const privateRequestBody = JSON.stringify(body);
   const preflight = await runPreflight({
@@ -316,6 +341,7 @@ async function handleChatCompletion({ apiBase, apiKey, secureState, req, res, co
           'x-nanogpt-private-model': model.id,
           'x-nanogpt-private-stream': privateStreamRequested ? 'true' : 'false',
           'x-nanogpt-private-cache-scope': buildPrivateModeCacheScopeProof(preflight.cacheScope),
+          [PRIVATE_MODE_PROXY_VERSION_HEADER]: PRIVATE_MODE_PROXY_VERSION,
           'x-query-source': 'api',
           ...copyLocalHeaders(req),
         },
@@ -364,59 +390,30 @@ async function handleChatCompletion({ apiBase, apiKey, secureState, req, res, co
     return;
   }
 
-  if (privateStreamRequested && response.body) {
+  if (isPrivateModeSseResponse(privateStreamRequested, response)) {
     res.writeHead(response.status, headers);
-    const reader = response.body.getReader();
-    const decoder = suppressReasoning ? new TextDecoder() : null;
-    const contentSuppressor = suppressReasoning
-      ? createPrivateModeReasoningContentSuppressor()
-      : null;
-    const sseChunkMetadata = {};
-    let sseBuffer = '';
-    let streamFailed = false;
     try {
-      while (true) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        if (res.destroyed) {
-          await reader.cancel('client disconnected');
-          upstreamAbortController.abort();
-          return;
-        }
-        if (!value) continue;
-        if (!suppressReasoning || !decoder || !contentSuppressor) {
-          res.write(Buffer.from(value));
-          continue;
-        }
-        sseBuffer += decoder.decode(value, { stream: true });
-        const { frames, remainder } = splitCompleteSseFrames(sseBuffer);
-        sseBuffer = remainder;
-        for (const frame of frames) {
-          res.write(`${suppressPrivateModeReasoningFromSseFrame(frame, contentSuppressor, sseChunkMetadata)}\n\n`);
-        }
-      }
-      if (suppressReasoning && decoder && contentSuppressor) {
-        sseBuffer += decoder.decode();
-        if (sseBuffer) {
-          res.write(`${suppressPrivateModeReasoningFromSseFrame(sseBuffer, contentSuppressor, sseChunkMetadata)}\n\n`);
-        }
-        const flushedContent = contentSuppressor.flush();
-        if (flushedContent) {
-          const finalDelta = buildPrivateModeSseContentDelta(flushedContent, sseChunkMetadata);
-          res.write(`data: ${finalDelta}\n\n`);
-        }
+      const outcome = await pipePrivateModeSseResponse({
+        body: response.body,
+        res,
+        suppressReasoning,
+        upstreamAbortController,
+        expectedChoiceCount,
+      });
+      // Successful completion and downstream disconnect still count as
+      // activity. Truncated or transport-failed streams keep the prior failure
+      // behavior and do not refresh the secure-client lifecycle.
+      if (!outcome.transportFailed && !outcome.streamFailed) {
+        secureState.markClientUsed(responseClient);
       }
     } catch (error) {
-      streamFailed = true;
       upstreamAbortController.abort();
       if (!res.destroyed) {
-        res.destroy(error instanceof Error ? error : new Error(String(error)));
+        process.stderr.write(`Private Mode stream pump failed: ${error instanceof Error ? error.message : String(error)}\n`);
       }
-      return;
     } finally {
       responseComplete = true;
-      if (!streamFailed) secureState.markClientUsed(responseClient);
-      if (!streamFailed && !res.writableEnded && !res.destroyed) res.end();
+      if (!res.writableEnded && !res.destroyed) res.end();
     }
     return;
   }
@@ -472,6 +469,19 @@ function handleOptions(req, res, corsHeaders) {
 
 export async function startPrivateModeProxy(options) {
   const apiBase = normalizeApiBase(options.apiBase);
+  const catalogCompatibility = await checkHostedPrivateModeCatalog({
+    apiBase,
+    localModels: MODELS,
+  });
+  if (catalogCompatibility.status === 'unavailable') {
+    throw new Error(buildPrivateModeCatalogUnavailableMessage(catalogCompatibility, apiBase));
+  }
+  if (hasPrivateModeCatalogMismatch(catalogCompatibility)) {
+    throw new Error(buildPrivateModeCatalogMismatchMessage(
+      catalogCompatibility,
+      PRIVATE_MODE_PROXY_VERSION,
+    ));
+  }
   const secureState = createSecureState(apiBase);
   const localBase = `http://${options.host}:${options.port}/v1`;
   const originPolicy = buildPrivateModeOriginPolicy(options);
@@ -497,7 +507,7 @@ export async function startPrivateModeProxy(options) {
       }
 
       if (req.method === 'GET' && url.pathname === '/health') {
-        jsonResponse(res, 200, privateModeStatus(apiBase, secureState, localBase, originPolicy), corsHeaders);
+        jsonResponse(res, 200, privateModeStatus(apiBase, secureState, localBase, originPolicy, catalogCompatibility), corsHeaders);
         return;
       }
 
@@ -507,7 +517,7 @@ export async function startPrivateModeProxy(options) {
       }
 
       if (req.method === 'GET' && url.pathname === '/v1/private-mode/status') {
-        jsonResponse(res, 200, privateModeStatus(apiBase, secureState, localBase, originPolicy), corsHeaders);
+        jsonResponse(res, 200, privateModeStatus(apiBase, secureState, localBase, originPolicy, catalogCompatibility), corsHeaders);
         return;
       }
 
@@ -543,7 +553,7 @@ export async function startPrivateModeProxy(options) {
       }
 
       if (req.method === 'GET' && url.pathname === '/') {
-        textResponse(res, 200, `NanoGPT Private Mode Proxy\nOpenAI base URL: ${localBase}\nStatus: /v1/private-mode/status\n`, corsHeaders);
+        textResponse(res, 200, `NanoGPT Private Mode Proxy v${PRIVATE_MODE_PROXY_VERSION}\nOpenAI base URL: ${localBase}\nStatus: /v1/private-mode/status\n`, corsHeaders);
         return;
       }
 
@@ -571,6 +581,7 @@ export async function startPrivateModeProxy(options) {
 
   if (options.quiet !== true) {
     process.stdout.write(`NanoGPT Private Mode Proxy
+Version: ${PRIVATE_MODE_PROXY_VERSION}
 Local base URL: ${localBase}
 NanoGPT API: ${apiBase}
 Models: ${MODELS.map((model) => model.id).join(', ')}

package/lib/serverErrorNormalization.js

@@ -6,7 +6,7 @@ const EHBP_RESPONSE_NONCE_HEADER = 'ehbp-response-nonce';
 const PRIVATE_MODE_REFUND_NOTICE = 'Any reserved balance will be released or refunded.';
 const MAX_UPSTREAM_ERROR_BODY_BYTES = 16 * 1024;
 const MAX_UPSTREAM_ERROR_MESSAGE_CHARS = 1_000;
-const HIDDEN_PROVIDER_NAME_PATTERN = /\b(?:openrouter|spoke\s*ai|aihubmix|ollama|mimas|comet|azure|digital\s*ocean|axionic|whale\s*ai|langfork)\b/gi;
+const HIDDEN_PROVIDER_NAME_PATTERN = /\b(?:openrouter|spoke\s*ai|aihubmix|mimas|comet|azure|digital\s*ocean|axionic|whale\s*ai|langfork)\b/gi;
 
 export function privateModeProviderFailureMessage(status) {
   if (status === 429) {

package/lib/sseResponsePump.js

@@ -0,0 +1,163 @@
+import {
+  buildPrivateModeSseContentDelta,
+  createPrivateModeReasoningContentSuppressor,
+  createPrivateModeSseTerminalGuard,
+  splitCompleteSseFrames,
+  suppressPrivateModeReasoningFromSseFrame,
+} from './requestTransforms.js';
+
+const MAX_SSE_FRAME_BYTES = 2 * 1024 * 1024;
+const DEFAULT_DOWNSTREAM_DRAIN_TIMEOUT_MS = 60 * 1000;
+
+function assertSseFrameWithinLimit(frame) {
+  if (Buffer.byteLength(frame, 'utf8') > MAX_SSE_FRAME_BYTES) {
+    throw new Error('Private Mode upstream SSE frame exceeded the proxy buffer limit.');
+  }
+}
+
+export function isPrivateModeSseResponse(streamRequested, response) {
+  const contentType = response?.headers?.get?.('content-type') || '';
+  return streamRequested === true
+    && Boolean(response?.body)
+    && contentType.toLowerCase().includes('text/event-stream');
+}
+
+function writeWithBackpressure(res, chunk, timeoutMs) {
+  if (res.destroyed || res.writableEnded) return Promise.resolve(false);
+  try {
+    if (res.write(chunk)) return Promise.resolve(true);
+  } catch {
+    return Promise.resolve(false);
+  }
+
+  return new Promise((resolve) => {
+    let drainTimer;
+    const cleanup = () => {
+      if (drainTimer) clearTimeout(drainTimer);
+      res.off('drain', onDrain);
+      res.off('close', onClose);
+      res.off('error', onError);
+    };
+    const settle = (writable) => {
+      cleanup();
+      resolve(writable);
+    };
+    const onDrain = () => settle(!res.destroyed && !res.writableEnded);
+    const onClose = () => settle(false);
+    const onError = () => settle(false);
+    res.once('drain', onDrain);
+    res.once('close', onClose);
+    res.once('error', onError);
+    drainTimer = setTimeout(() => settle(false), timeoutMs);
+    drainTimer.unref?.();
+  });
+}
+
+export async function pipePrivateModeSseResponse({
+  body,
+  res,
+  suppressReasoning,
+  upstreamAbortController,
+  expectedChoiceCount = 1,
+  downstreamDrainTimeoutMs = DEFAULT_DOWNSTREAM_DRAIN_TIMEOUT_MS,
+}) {
+  let reader;
+  const decoder = new TextDecoder();
+  const contentSuppressor = suppressReasoning
+    ? createPrivateModeReasoningContentSuppressor()
+    : null;
+  const terminalGuard = createPrivateModeSseTerminalGuard(expectedChoiceCount);
+  const sseChunkMetadata = {};
+  let sseBuffer = '';
+  let transportFailed = false;
+
+  const writeFrame = async (frame) => {
+    if (!frame) return true;
+    return writeWithBackpressure(res, `${frame}\n\n`, downstreamDrainTimeoutMs);
+  };
+  const forwardFrame = async (frame) => {
+    const forwarded = suppressReasoning && contentSuppressor
+      ? suppressPrivateModeReasoningFromSseFrame(frame, contentSuppressor, sseChunkMetadata)
+      : frame;
+    return writeFrame(terminalGuard.observe(frame, forwarded));
+  };
+  const finishStream = async () => {
+    // A complete terminal sequence may be released before transport EOF.
+    // Never append a defensive suppressor flush after that marker.
+    if (contentSuppressor && !terminalGuard.hasEmittedDone()) {
+      const flushedContent = contentSuppressor.flush();
+      if (flushedContent) {
+        const delta = buildPrivateModeSseContentDelta(flushedContent, sseChunkMetadata);
+        if (!await writeFrame(`data: ${delta}`)) return null;
+      }
+    }
+    const terminal = terminalGuard.finish();
+    if (!await writeFrame(terminal.frame)) return null;
+    return terminal;
+  };
+
+  try {
+    reader = body.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (res.destroyed || res.writableEnded) {
+        await reader.cancel('client disconnected').catch(() => {});
+        upstreamAbortController.abort();
+        return { streamFailed: false, clientDisconnected: true, transportFailed: false };
+      }
+      if (!value) continue;
+      sseBuffer += decoder.decode(value, { stream: true });
+      const { frames, remainder } = splitCompleteSseFrames(sseBuffer);
+      sseBuffer = remainder;
+      assertSseFrameWithinLimit(sseBuffer);
+      for (const frame of frames) {
+        assertSseFrameWithinLimit(frame);
+        if (!await forwardFrame(frame)) {
+          await reader.cancel('client disconnected').catch(() => {});
+          upstreamAbortController.abort();
+          return { streamFailed: false, clientDisconnected: true, transportFailed: false };
+        }
+      }
+    }
+    sseBuffer += decoder.decode();
+    if (sseBuffer && !await forwardFrame(sseBuffer)) {
+      await reader.cancel('client disconnected').catch(() => {});
+      upstreamAbortController.abort();
+      return { streamFailed: false, clientDisconnected: true, transportFailed: false };
+    }
+  } catch (error) {
+    transportFailed = true;
+    upstreamAbortController.abort();
+    process.stderr.write(`Private Mode upstream stream failed: ${error instanceof Error ? error.message : String(error)}\n`);
+  }
+
+  if (res.destroyed || res.writableEnded) {
+    upstreamAbortController.abort();
+    return { streamFailed: false, clientDisconnected: true, transportFailed };
+  }
+
+  let terminal;
+  try {
+    terminal = await finishStream();
+  } catch (error) {
+    transportFailed = true;
+    upstreamAbortController.abort();
+    process.stderr.write(`Private Mode stream finalization failed: ${error instanceof Error ? error.message : String(error)}\n`);
+    if (!terminalGuard.hasEmittedDone()) {
+      await writeFrame(`data: ${JSON.stringify({
+        error: {
+          message: 'Private Mode stream ended before a complete terminal sequence. The response may be partial; retry the request.',
+          type: 'api_error',
+          code: 'private_stream_incomplete',
+        },
+      })}`);
+    }
+    return { streamFailed: true, clientDisconnected: false, transportFailed };
+  }
+  if (!terminal) {
+    upstreamAbortController.abort();
+    return { streamFailed: false, clientDisconnected: true, transportFailed };
+  }
+  return { streamFailed: !terminal.complete, clientDisconnected: false, transportFailed };
+}

package/lib/statusContract.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 
 export const PRIVATE_MODE_FRONTEND_SUPPORTED_FEATURES = Object.freeze([
   'text_chat',
+  'vision_image_inputs',
   'streaming',
   'conversation_history',
   'model_settings',
@@ -9,7 +10,7 @@ export const PRIVATE_MODE_FRONTEND_SUPPORTED_FEATURES = Object.freeze([
 ]);
 
 export const PRIVATE_MODE_FRONTEND_DISABLED_FEATURES = Object.freeze([
-  'attachments',
+  'non_image_attachments',
   'web_search',
   'url_scraped_content',
   'project_chats',

package/models/private-tee.json

@@ -1,12 +1,13 @@
 [
   {
     "id": "private/deepseek-v4-flash",
-    "name": "DeepSeek V4 Flash Private",
+    "name": "DeepSeek V4 Flash 0731 Private",
     "upstreamModel": "deepseek-v4-flash",
     "billingModel": "private/deepseek-v4-flash",
     "providerPricingModel": "TEE/deepseek-v4-flash",
     "teeTargetModel": "deepseek-v4-flash",
     "thinkingMode": "deepseek-v4",
+    "maxInputTokens": 1048576,
     "maxOutputTokens": 1048576,
     "created": 1786406400,
     "ownedBy": "nanogpt-private-mode",
@@ -55,6 +56,8 @@
     "providerPricingModel": "TEE/glm-5.2",
     "teeTargetModel": "glm-5-2",
     "thinkingMode": "glm-5.2",
+    "maxInputTokens": 393216,
+    "maxOutputTokens": 131072,
     "created": 1781827200,
     "ownedBy": "nanogpt-private-mode",
     "aliases": ["private/glm-5.2", "TEE/glm-5-2", "TEE/glm-5.2"]
@@ -67,10 +70,40 @@
     "providerPricingModel": "TEE/glm-5.2:thinking",
     "teeTargetModel": "glm-5-2",
     "thinkingMode": "glm-5.2",
+    "maxInputTokens": 393216,
+    "maxOutputTokens": 131072,
     "created": 1781827200,
     "ownedBy": "nanogpt-private-mode",
     "aliases": ["private/glm-5.2:thinking", "TEE/glm-5-2:thinking", "TEE/glm-5.2:thinking"]
   },
+  {
+    "id": "private/glm-5-3",
+    "name": "GLM 5.3 Private",
+    "upstreamModel": "glm-5-3",
+    "billingModel": "TEE/glm-5.3",
+    "providerPricingModel": "TEE/glm-5.3",
+    "teeTargetModel": "glm-5-3",
+    "maxInputTokens": 1048576,
+    "maxOutputTokens": 131072,
+    "thinkingMode": "glm-5.3",
+    "created": 1788391929,
+    "ownedBy": "nanogpt-private-mode",
+    "aliases": ["private/glm-5.3", "TEE/glm-5-3", "TEE/glm-5.3"]
+  },
+  {
+    "id": "private/glm-5-3-flash",
+    "name": "GLM 5.3 Flash Private",
+    "upstreamModel": "glm-5-3-flash",
+    "billingModel": "TEE/glm-5.3-flash",
+    "providerPricingModel": "TEE/glm-5.3-flash",
+    "teeTargetModel": "glm-5-3-flash",
+    "maxInputTokens": 1048576,
+    "maxOutputTokens": 131072,
+    "thinkingMode": "glm-5.3",
+    "created": 1788307200,
+    "ownedBy": "nanogpt-private-mode",
+    "aliases": ["private/glm-5.3-flash", "TEE/glm-5-3-flash", "TEE/glm-5.3-flash"]
+  },
   {
     "id": "private/gemma4-31b",
     "name": "Gemma 4 31B Private",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanogpt/private-mode",
-  "version": "0.2.9",
+  "version": "0.2.13",
   "description": "OpenAI-compatible localhost proxy for NanoGPT Private Mode.",
   "type": "module",
   "publishConfig": {
@@ -13,11 +13,15 @@
   "files": [
     "bin",
     "lib/cacheScope.js",
+    "lib/catalogCompatibility.js",
+    "lib/constants.js",
     "lib/originPolicy.js",
+    "lib/packageInfo.js",
     "lib/requestTransforms.js",
     "lib/secureClientLifecycle.js",
     "lib/server.js",
     "lib/serverErrorNormalization.js",
+    "lib/sseResponsePump.js",
     "lib/statusContract.js",
     "lib/verifyReceipt.js",
     "models",