docs(routes): document fail-closed tool discovery, stream buffering, partial-error semantics

Author: samson910022

src/proxy.ts

@@ -707,6 +707,10 @@ export function createApp(config: ProxyConfig): CreateAppResult {
       }
       const normalized = normalizeBackendToolIds(data);
       if (normalized.length === 0) {
+        // Fail-closed by design (locked by tests/tool-alias.test.js): an empty
+        // tool list under DISABLE_TOOLS=true is treated as unverifiable
+        // discovery, not as "zero tools, proceed". A real backend always exposes
+        // tools; empty almost certainly means a broken backend/proxy skew.
         if (DISABLE_TOOLS) {
           throw new Error('tool discovery returned empty ids');
         }

src/routes/chat.ts

@@ -432,6 +432,8 @@ export function registerChatRoutes(app: Application, ctx: AppContext): void {
               REQUEST_TIMEOUT_MS,
               'load tool overrides',
             )) as Record<string, boolean> | null;
+            // Fail-closed by design: null (discovery failed) or verified-empty (no
+            // tool IDs to disable) both 503. A real backend always exposes tools.
             if (DISABLE_TOOLS && (!toolOverrides || Object.keys(toolOverrides).length === 0)) {
               try {
                 await activeClient.session.delete({ path: { id: sessionId as string } });
@@ -484,8 +486,12 @@ export function registerChatRoutes(app: Application, ctx: AppContext): void {
              };
            }
 
-           if (stream) {
-
+            if (stream) {
+              // Intentional: buffer visible text while any external tool contract is
+              // declared so `<function_calls>` / `<external__*>` markup fragments are
+              // never streamed incrementally before the parser can classify them.
+              // Trade-off: pure-text turns with tools declared also emit in one batch
+              // at completion instead of incrementally.
               const shouldBufferExternalStream = externalToolRegistry.length > 0;
               let filterContentDelta = createToolCallFilter({
                 disableTools: DISABLE_TOOLS,
@@ -1032,6 +1038,10 @@ export function registerChatRoutes(app: Application, ctx: AppContext): void {
                 }
                 break;
               }
+              // Fail-closed: any backend error fails even when partial content exists.
+              // Returning partial text as success would hide the upstream failure and
+              // diverge from stream paths (which throw on snapshot.error). Retry above
+              // already covers the no-output transient case.
               if (error != null) {
                 if (/^Request timeout after/.test(toErrorMessage(error))) throw error;
                 const normalizedDiscovery = normalizeBackendError(error);

src/routes/interactions.ts

@@ -272,6 +272,7 @@ export function registerInteractionsRoutes(app: Application, ctx: AppContext): v
           toolOverrides = merged;
         }
       }
+      // Fail-closed by design (see chat.ts): null or verified-empty both 503.
       if (DISABLE_TOOLS && (!toolOverrides || Object.keys(toolOverrides).length === 0)) {
         res.status(503).json({
           error: {

src/routes/messages.ts

@@ -330,6 +330,7 @@ export function registerMessagesRoutes(app: Application, ctx: AppContext): void
             REQUEST_TIMEOUT_MS,
             'load tool overrides',
           )) as Record<string, boolean> | null;
+          // Fail-closed by design (see chat.ts): null or verified-empty both 503.
           if (DISABLE_TOOLS && (!toolOverrides || Object.keys(toolOverrides).length === 0)) {
             try {
               await activeClient.session.delete({ path: { id: sessionId as string } });
@@ -449,6 +450,7 @@ export function registerMessagesRoutes(app: Application, ctx: AppContext): void
               if (error && !content && !reasoning && attempt < maxAttempts && isTransientUpstreamError(error)) continue;
               break;
             }
+              // Fail-closed: any backend error fails even with partial content (see chat.ts).
                           if (error != null) {
               const t = transformUpstreamError(error);
               res.status(t.statusCode).json({
@@ -538,6 +540,9 @@ export function registerMessagesRoutes(app: Application, ctx: AppContext): void
           let rawContent = '';
           let rawReasoning = '';
            const streamedToolCalls: FinalToolCall[] = [];
+           // Intentional: buffer while any external tool contract is declared so tool
+           // markup is never emitted as incremental `content_block_delta` before it
+           // can be classified. Pure-text turns with tools declared also batch.
            const shouldBufferExternalStream = externalToolRegistry.length > 0;
            const filterContent = createToolCallFilter({ disableTools: DISABLE_TOOLS, forceStrip: shouldBufferExternalStream, registry: externalToolRegistry });
            const filterReasoning = createToolCallFilter({ disableTools: DISABLE_TOOLS, forceStrip: shouldBufferExternalStream, registry: externalToolRegistry });

src/routes/responses.ts

@@ -729,6 +729,7 @@ export function registerResponsesRoutes(app: Application, ctx: AppContext): void
           return;
         }
       }
+      // Fail-closed by design (see chat.ts): null or verified-empty both 503.
       if (DISABLE_TOOLS && (!toolOverrides || Object.keys(toolOverrides).length === 0)) {
         await cleanupOwnedResponsesSession();
         if (stream) {
@@ -1007,6 +1008,8 @@ export function registerResponsesRoutes(app: Application, ctx: AppContext): void
           }
         };
         responseState.finalize = () => finalizeOutputItems();
+        // Intentional: buffer while any external tool contract is declared so tool
+        // markup is never streamed before classification. Pure-text turns also batch.
         const shouldBufferExternalStream = externalToolRegistry.length > 0;
         const deferVisibleOutput = shouldBufferExternalStream || hostedSearch.requested;
         let filterContentDelta = createToolCallFilter({ disableTools: DISABLE_TOOLS, forceStrip: shouldBufferExternalStream, registry: externalToolRegistry });