graphlit-client 1.0.20260217005 → 1.0.20260218002

package/dist/client.d.ts

@@ -3,7 +3,8 @@ import type { NormalizedCacheObject } from "@apollo/client/core/index.js";
 import * as Types from "./generated/graphql-types.js";
 import { AgentOptions, AgentResult, StreamAgentOptions, ToolHandler } from "./types/agent.js";
 import { AgentStreamEvent } from "./types/ui-events.js";
-export type { AgentOptions, AgentResult, ArtifactCollector, StreamAgentOptions, ToolCallResult, UsageInfo, AgentError, } from "./types/agent.js";
+export type { AgentOptions, AgentResult, ArtifactCollector, ContextStrategy, ContextManagementAction, StreamAgentOptions, ToolCallResult, UsageInfo, AgentError, } from "./types/agent.js";
+export { TokenBudgetTracker, truncateToolResult, estimateTokens, isAccurateTokenCounting, } from "./helpers/context-management.js";
 export type { AgentStreamEvent } from "./types/ui-events.js";
 export interface RetryConfig {
     /** Maximum number of retry attempts (default: 5) */
@@ -803,12 +804,12 @@ declare class Graphlit {
      */
     queryConversationsGraph(filter?: Types.ConversationFilter, correlationId?: string): Promise<Types.QueryConversationsGraphQuery>;
     /**
-    * Retrieves Conversations with clustering.
-    * @param filter - The filter criteria to apply when retrieving Conversations, optional.
-    * @param clusters - The clustering input parameters, optional.
-    * @param correlationId - The tenant correlation identifier, optional.
-    * @returns The Conversations with clusters.
-    */
+     * Retrieves Conversations with clustering.
+     * @param filter - The filter criteria to apply when retrieving Conversations, optional.
+     * @param clusters - The clustering input parameters, optional.
+     * @param correlationId - The tenant correlation identifier, optional.
+     * @returns The Conversations with clusters.
+     */
     queryConversationsClusters(filter?: Types.ConversationFilter, clusters?: Types.EntityClustersInput, correlationId?: string): Promise<Types.QueryConversationsClustersQuery>;
     /**
      * Counts conversations based on the provided filter criteria.

package/dist/client.js

@@ -6,6 +6,7 @@ import { RetryLink } from "@apollo/client/link/retry/index.js";
 import * as Types from "./generated/graphql-types.js";
 import * as Documents from "./generated/graphql-documents.js";
 import { getServiceType, getModelName, getModelEnum } from "./model-mapping.js";
+import { TokenBudgetTracker, truncateToolResult, windowToolRounds, estimateTokens, DEFAULT_CONTEXT_STRATEGY, } from "./helpers/context-management.js";
 import { UIEventAdapter } from "./streaming/ui-event-adapter.js";
 import { formatMessagesForOpenAI, formatMessagesForAnthropic, formatMessagesForGoogle, formatMessagesForMistral, formatMessagesForBedrock, } from "./streaming/llm-formatters.js";
 import { streamWithOpenAI, streamWithAnthropic, streamWithGoogle, streamWithGroq, streamWithCerebras, streamWithCohere, streamWithMistral, streamWithBedrock, streamWithDeepseek, streamWithXai, } from "./streaming/providers.js";
@@ -124,7 +125,9 @@ catch (e) {
         console.log("[SDK Loading] Cerebras SDK not found:", e.message);
     }
 }
-const DEFAULT_MAX_TOOL_ROUNDS = 1000;
+const DEFAULT_MAX_TOOL_ROUNDS = 100;
+// Re-export context management utilities
+export { TokenBudgetTracker, truncateToolResult, estimateTokens, isAccurateTokenCounting, } from "./helpers/context-management.js";
 // Helper function to validate GUID format
 function isValidGuid(guid) {
     if (!guid)
@@ -1534,12 +1537,12 @@ class Graphlit {
         });
     }
     /**
-    * Retrieves Conversations with clustering.
-    * @param filter - The filter criteria to apply when retrieving Conversations, optional.
-    * @param clusters - The clustering input parameters, optional.
-    * @param correlationId - The tenant correlation identifier, optional.
-    * @returns The Conversations with clusters.
-    */
+     * Retrieves Conversations with clustering.
+     * @param filter - The filter criteria to apply when retrieving Conversations, optional.
+     * @param clusters - The clustering input parameters, optional.
+     * @param correlationId - The tenant correlation identifier, optional.
+     * @returns The Conversations with clusters.
+     */
     async queryConversationsClusters(filter, clusters, correlationId) {
         return this.queryAndCheckError(Documents.QueryConversationsClusters, {
             filter: filter,
@@ -3131,7 +3134,10 @@ class Graphlit {
      * @returns The organizations.
      */
     async queryOrganizations(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryOrganizations, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryOrganizations, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /**
      * Retrieves organizations with clustering information.
@@ -3352,7 +3358,10 @@ class Graphlit {
      * @returns The emotions.
      */
     async queryEmotions(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryEmotions, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryEmotions, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /**
      * Counts emotions based on the provided filter criteria.
@@ -3518,7 +3527,10 @@ class Graphlit {
      * @returns The products.
      */
     async queryProducts(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryProducts, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryProducts, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /**
      * Retrieves products with clustering information.
@@ -3712,7 +3724,10 @@ class Graphlit {
      * @returns The software.
      */
     async querySoftwares(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QuerySoftwares, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QuerySoftwares, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /**
      * Retrieves software with clustering information.
@@ -3773,7 +3788,10 @@ class Graphlit {
     }
     /** Retrieves medical conditions based on filter criteria. */
     async queryMedicalConditions(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalConditions, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalConditions, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical conditions with clustering information. */
     async queryMedicalConditionsClusters(filter, clusters, correlationId) {
@@ -3823,7 +3841,10 @@ class Graphlit {
     }
     /** Retrieves medical guidelines based on filter criteria. */
     async queryMedicalGuidelines(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalGuidelines, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalGuidelines, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical guidelines with clustering information. */
     async queryMedicalGuidelinesClusters(filter, clusters, correlationId) {
@@ -3869,7 +3890,10 @@ class Graphlit {
     }
     /** Retrieves medical drugs based on filter criteria. */
     async queryMedicalDrugs(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalDrugs, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalDrugs, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical drugs with clustering information. */
     async queryMedicalDrugsClusters(filter, clusters, correlationId) {
@@ -3923,7 +3947,10 @@ class Graphlit {
     }
     /** Retrieves medical indications based on filter criteria. */
     async queryMedicalIndications(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalIndications, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalIndications, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical indications with clustering information. */
     async queryMedicalIndicationsClusters(filter, clusters, correlationId) {
@@ -3977,7 +4004,10 @@ class Graphlit {
     }
     /** Retrieves medical contraindications based on filter criteria. */
     async queryMedicalContraindications(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalContraindications, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalContraindications, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical contraindications with clustering information. */
     async queryMedicalContraindicationsClusters(filter, clusters, correlationId) {
@@ -4024,7 +4054,10 @@ class Graphlit {
     }
     /** Retrieves medical tests based on filter criteria. */
     async queryMedicalTests(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalTests, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalTests, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical tests with clustering information. */
     async queryMedicalTestsClusters(filter, clusters, correlationId) {
@@ -4074,7 +4107,10 @@ class Graphlit {
     }
     /** Retrieves medical devices based on filter criteria. */
     async queryMedicalDevices(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalDevices, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalDevices, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical devices with clustering information. */
     async queryMedicalDevicesClusters(filter, clusters, correlationId) {
@@ -4124,7 +4160,10 @@ class Graphlit {
     }
     /** Retrieves medical procedures based on filter criteria. */
     async queryMedicalProcedures(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalProcedures, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalProcedures, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical procedures with clustering information. */
     async queryMedicalProceduresClusters(filter, clusters, correlationId) {
@@ -4174,7 +4213,10 @@ class Graphlit {
     }
     /** Retrieves medical studies based on filter criteria. */
     async queryMedicalStudies(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalStudies, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalStudies, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical studies with clustering information. */
     async queryMedicalStudiesClusters(filter, clusters, correlationId) {
@@ -4224,7 +4266,10 @@ class Graphlit {
     }
     /** Retrieves medical drug classes based on filter criteria. */
     async queryMedicalDrugClasses(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalDrugClasses, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalDrugClasses, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical drug classes with clustering information. */
     async queryMedicalDrugClassesClusters(filter, clusters, correlationId) {
@@ -4274,7 +4319,10 @@ class Graphlit {
     }
     /** Retrieves medical therapies based on filter criteria. */
     async queryMedicalTherapies(filter, correlationId) {
-        return this.queryAndCheckError(Documents.QueryMedicalTherapies, { filter: filter, correlationId: correlationId });
+        return this.queryAndCheckError(Documents.QueryMedicalTherapies, {
+            filter: filter,
+            correlationId: correlationId,
+        });
     }
     /** Retrieves medical therapies with clustering information. */
     async queryMedicalTherapiesClusters(filter, clusters, correlationId) {
@@ -4612,13 +4660,17 @@ class Graphlit {
             let totalTokens = currentMessage?.tokens || 0;
             const toolStartTime = Date.now();
             let toolTime = 0;
+            // Context strategy for tool result truncation
+            const strategy = options?.contextStrategy ?? {};
+            const toolResultTokenLimit = strategy.toolResultTokenLimit ??
+                DEFAULT_CONTEXT_STRATEGY.toolResultTokenLimit;
             while (currentMessage.toolCalls?.length &&
                 rounds < maxRounds &&
                 !abortController.signal.aborted) {
                 rounds++;
-                // Execute tools
+                // Execute tools (with truncation)
                 const toolExecStart = Date.now();
-                const toolResults = await this.executeToolsForPromptAgent(currentMessage.toolCalls.filter((tc) => tc !== null), toolHandlers || {}, allToolCalls, abortController.signal);
+                const toolResults = await this.executeToolsForPromptAgent(currentMessage.toolCalls.filter((tc) => tc !== null), toolHandlers || {}, allToolCalls, abortController.signal, toolResultTokenLimit);
                 toolTime += Date.now() - toolExecStart;
                 if (abortController.signal.aborted) {
                     throw new Error("Operation timed out");
@@ -4701,7 +4753,9 @@ class Graphlit {
         // Swallow errors from the previous call so a failed message doesn't
         // permanently block the queue for this conversation.
         // Check the abort signal before starting work so ESC while queued is instant.
-        const next = previous.catch(() => { }).then(() => {
+        const next = previous
+            .catch(() => { })
+            .then(() => {
             if (abortSignal?.aborted)
                 throw new Error("Operation aborted");
             return work();
@@ -4862,7 +4916,7 @@ class Graphlit {
                     modelService: serviceType,
                 });
                 // Start the streaming conversation
-                await this.executeStreamingAgent(prompt, actualConversationId, fullSpec, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona);
+                await this.executeStreamingAgent(prompt, actualConversationId, fullSpec, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, options?.contextStrategy);
             }, abortSignal);
         }
         catch (error) {
@@ -4908,9 +4962,10 @@ class Graphlit {
     /**
      * Execute the streaming agent workflow with tool calling loop
      */
-    async executeStreamingAgent(prompt, conversationId, specification, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona) {
+    async executeStreamingAgent(prompt, conversationId, specification, tools, toolHandlers, uiAdapter, maxRounds, abortSignal, mimeType, data, correlationId, persona, contextStrategy) {
         let currentRound = 0;
         let fullMessage = "";
+        const contextActions = [];
         // Collects artifact content IDs from tool handlers (e.g. code_execution).
         // Handlers register async ingestion promises; we await all of them before
         // completeConversation so the IDs are available without blocking the LLM.
@@ -4965,8 +5020,30 @@ class Graphlit {
                 console.log(`📊 [Context Window] Using ${usedTokens.toLocaleString()}/${details.tokenLimit.toLocaleString()} tokens (${Math.round((usedTokens / details.tokenLimit) * 100)}%)`);
             }
         }
+        // Initialize context management
+        const budgetTracker = details
+            ? TokenBudgetTracker.fromDetails(details)
+            : undefined;
+        // Merge: caller overrides > server-side specification strategy > defaults
+        const callerStrategy = contextStrategy ?? {};
+        const serverStrategy = specification.strategy;
+        const toolResultTokenLimit = callerStrategy.toolResultTokenLimit ??
+            serverStrategy?.toolResultTokenLimit ??
+            DEFAULT_CONTEXT_STRATEGY.toolResultTokenLimit;
+        const toolRoundLimit = callerStrategy.toolRoundLimit ??
+            serverStrategy?.toolRoundLimit ??
+            DEFAULT_CONTEXT_STRATEGY.toolRoundLimit;
+        const rebudgetThreshold = callerStrategy.rebudgetThreshold ??
+            serverStrategy?.toolBudgetThreshold ??
+            DEFAULT_CONTEXT_STRATEGY.rebudgetThreshold;
+        if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING && budgetTracker) {
+            console.log(`📊 [Context Management] Initialized budget tracker: ${budgetTracker.usagePercent}% used, ` +
+                `${budgetTracker.remaining.toLocaleString()} tokens remaining. ` +
+                `Strategy: toolResultLimit=${toolResultTokenLimit}, toolRoundLimit=${toolRoundLimit}, ` +
+                `rebudgetThreshold=${rebudgetThreshold}`);
+        }
         // Build message array with conversation history
-        const messages = [];
+        let messages = [];
         // Add system prompt if specified
         if (specification.systemPrompt) {
             messages.push({
@@ -5033,6 +5110,41 @@ class Graphlit {
             if (abortSignal?.aborted) {
                 throw new Error("Operation aborted");
             }
+            // Context window management: check budget before sending to LLM
+            if (budgetTracker && currentRound > 0) {
+                if (budgetTracker.needsRebudget(rebudgetThreshold)) {
+                    const beforeUsage = budgetTracker.usagePercent;
+                    const beforeCount = messages.length;
+                    messages = windowToolRounds(messages, toolRoundLimit);
+                    budgetTracker.resetFromMessages(messages);
+                    const afterUsage = budgetTracker.usagePercent;
+                    const droppedRounds = Math.max(0, Math.floor((beforeCount - messages.length) / 2));
+                    if (droppedRounds > 0) {
+                        const action = {
+                            type: "windowed_tool_rounds",
+                            droppedRounds,
+                            keptRounds: toolRoundLimit,
+                        };
+                        contextActions.push(action);
+                        // Notify the UI
+                        uiAdapter.handleEvent({
+                            type: "context_management",
+                            action,
+                            usage: budgetTracker.getUsageSnapshot(),
+                            timestamp: new Date(),
+                        });
+                        if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING) {
+                            console.log(`📊 [Context Management] Windowed tool rounds: dropped ${droppedRounds} round(s), ` +
+                                `budget ${beforeUsage}% → ${afterUsage}% (${messages.length} messages)`);
+                        }
+                    }
+                    // Emit updated context window
+                    uiAdapter.handleEvent({
+                        type: "context_window",
+                        usage: budgetTracker.getUsageSnapshot(),
+                    });
+                }
+            }
             let toolCalls = [];
             let roundMessage = "";
             // Stream with appropriate provider
@@ -5299,6 +5411,12 @@ class Graphlit {
                     timestamp: new Date().toISOString(),
                 };
                 messages.push(assistantMessage);
+                // Track assistant message in budget (includes tool call arguments)
+                if (budgetTracker) {
+                    const assistantTokens = estimateTokens(roundMessage) +
+                        toolCalls.reduce((sum, tc) => sum + estimateTokens(tc.arguments), 0);
+                    budgetTracker.addMessage("", assistantTokens);
+                }
                 // Execute tools and add responses
                 for (const toolCall of toolCalls) {
                     const handler = toolHandlers[toolCall.name];
@@ -5395,17 +5513,45 @@ class Graphlit {
                             },
                             result: result,
                         });
-                        // Add tool response to messages
+                        // Add tool response to messages (with truncation)
+                        const rawResult = typeof result === "string" ? result : JSON.stringify(result);
+                        const truncatedResult = truncateToolResult(rawResult, toolResultTokenLimit, toolCall.name);
+                        // Track truncation for observability
+                        if (truncatedResult.length < rawResult.length) {
+                            const action = {
+                                type: "truncated_tool_result",
+                                toolName: toolCall.name,
+                                originalTokens: estimateTokens(rawResult),
+                                truncatedTokens: estimateTokens(truncatedResult),
+                            };
+                            contextActions.push(action);
+                            if (budgetTracker) {
+                                uiAdapter.handleEvent({
+                                    type: "context_management",
+                                    action,
+                                    usage: budgetTracker.getUsageSnapshot(),
+                                    timestamp: new Date(),
+                                });
+                            }
+                            if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING) {
+                                console.log(`📊 [Context Management] Truncated tool result for ${toolCall.name}: ` +
+                                    `${estimateTokens(rawResult)} → ${estimateTokens(truncatedResult)} tokens`);
+                            }
+                        }
                         const toolMessage = {
                             __typename: "ConversationMessage",
                             role: Types.ConversationRoleTypes.Tool,
-                            message: typeof result === "string" ? result : JSON.stringify(result),
+                            message: truncatedResult,
                             toolCallId: toolCall.id,
                             timestamp: new Date().toISOString(),
                         };
                         // Add tool name for Mistral compatibility
                         toolMessage.toolName = toolCall.name;
                         messages.push(toolMessage);
+                        // Track budget
+                        if (budgetTracker) {
+                            budgetTracker.addMessage(truncatedResult);
+                        }
                     }
                     catch (error) {
                         const errorMessage = error instanceof Error ? error.message : "Unknown error";
@@ -5421,19 +5567,30 @@ class Graphlit {
                             error: errorMessage,
                         });
                         // Add error response
+                        const errorText = `Error: ${errorMessage}`;
                         const errorToolMessage = {
                             __typename: "ConversationMessage",
                             role: Types.ConversationRoleTypes.Tool,
-                            message: `Error: ${errorMessage}`,
+                            message: errorText,
                             toolCallId: toolCall.id,
                             timestamp: new Date().toISOString(),
                         };
                         // Add tool name for Mistral compatibility
                         errorToolMessage.toolName = toolCall.name;
                         messages.push(errorToolMessage);
+                        if (budgetTracker) {
+                            budgetTracker.addMessage(errorText);
+                        }
                     }
                 }
             }
+            // Emit context window usage after each tool round
+            if (budgetTracker) {
+                uiAdapter.handleEvent({
+                    type: "context_window",
+                    usage: budgetTracker.getUsageSnapshot(),
+                });
+            }
             currentRound++;
         }
         // Complete the conversation and get token count
@@ -5859,7 +6016,7 @@ class Graphlit {
         await streamWithXai(specification, messages, tools, xaiClient, (event) => uiAdapter.handleEvent(event), onComplete, abortSignal);
     }
     // Helper method to execute tools for promptAgent
-    async executeToolsForPromptAgent(toolCalls, toolHandlers, allToolCalls, signal) {
+    async executeToolsForPromptAgent(toolCalls, toolHandlers, allToolCalls, signal, toolResultTokenLimit = DEFAULT_CONTEXT_STRATEGY.toolResultTokenLimit) {
         const responses = [];
         // Execute tools in parallel for better performance
         const toolPromises = toolCalls.map(async (toolCall) => {
@@ -5892,10 +6049,18 @@ class Graphlit {
                 duration: Date.now() - startTime,
             };
             allToolCalls.push(toolResult);
+            // Truncate oversized tool results before sending to server
+            const rawContent = error ? error : result ? JSON.stringify(result) : "";
+            const content = truncateToolResult(rawContent, toolResultTokenLimit, toolCall.name || "unknown");
+            if (content.length < rawContent.length &&
+                process.env.DEBUG_GRAPHLIT_SDK_STREAMING) {
+                console.log(`📊 [Context Management] Truncated tool result for ${toolCall.name}: ` +
+                    `${estimateTokens(rawContent)} → ${estimateTokens(content)} tokens (promptAgent path)`);
+            }
             // Response for API
             return {
                 id: toolCall.id,
-                content: error ? error : result ? JSON.stringify(result) : "",
+                content,
             };
         });
         const results = await Promise.all(toolPromises);

package/dist/generated/graphql-documents.js

@@ -16098,6 +16098,9 @@ export const GetSpecification = gql `
       factExtractionLimit
       messagesWeight
       contentsWeight
+      toolResultTokenLimit
+      toolRoundLimit
+      toolBudgetThreshold
     }
     promptStrategy {
       type
@@ -16492,6 +16495,9 @@ export const QuerySpecifications = gql `
         factExtractionLimit
         messagesWeight
         contentsWeight
+        toolResultTokenLimit
+        toolRoundLimit
+        toolBudgetThreshold
       }
       promptStrategy {
         type

package/dist/generated/graphql-types.d.ts

@@ -3755,6 +3755,12 @@ export type ConversationStrategy = {
     messageLimit?: Maybe<Scalars['Int']['output']>;
     /** The weight of conversation messages within prompt context, in range [0.0 - 1.0]. */
     messagesWeight?: Maybe<Scalars['Float']['output']>;
+    /** The fraction of token budget at which tool round windowing is triggered, in range [0.0 - 1.0]. */
+    toolBudgetThreshold?: Maybe<Scalars['Float']['output']>;
+    /** The maximum number of tokens for a single tool result. Results exceeding this limit are truncated. */
+    toolResultTokenLimit?: Maybe<Scalars['Int']['output']>;
+    /** The maximum number of tool call/response rounds to keep in context. Older rounds are dropped. */
+    toolRoundLimit?: Maybe<Scalars['Int']['output']>;
     /** The conversation strategy type. */
     type?: Maybe<ConversationStrategyTypes>;
 };
@@ -3782,6 +3788,12 @@ export type ConversationStrategyInput = {
     messageLimit?: InputMaybe<Scalars['Int']['input']>;
     /** The weight of conversation messages within prompt context, in range [0.0 - 1.0]. */
     messagesWeight?: InputMaybe<Scalars['Float']['input']>;
+    /** The fraction of token budget at which tool round windowing is triggered, in range [0.0 - 1.0]. */
+    toolBudgetThreshold?: InputMaybe<Scalars['Float']['input']>;
+    /** The maximum number of tokens for a single tool result. Results exceeding this limit are truncated. */
+    toolResultTokenLimit?: InputMaybe<Scalars['Int']['input']>;
+    /** The maximum number of tool call/response rounds to keep in context. Older rounds are dropped. */
+    toolRoundLimit?: InputMaybe<Scalars['Int']['input']>;
     /** The conversation strategy type. */
     type?: InputMaybe<ConversationStrategyTypes>;
 };
@@ -3816,6 +3828,12 @@ export type ConversationStrategyUpdateInput = {
     messageLimit?: InputMaybe<Scalars['Int']['input']>;
     /** The weight of conversation messages within prompt context, in range [0.0 - 1.0]. */
     messagesWeight?: InputMaybe<Scalars['Float']['input']>;
+    /** The fraction of token budget at which tool round windowing is triggered, in range [0.0 - 1.0]. */
+    toolBudgetThreshold?: InputMaybe<Scalars['Float']['input']>;
+    /** The maximum number of tokens for a single tool result. Results exceeding this limit are truncated. */
+    toolResultTokenLimit?: InputMaybe<Scalars['Int']['input']>;
+    /** The maximum number of tool call/response rounds to keep in context. Older rounds are dropped. */
+    toolRoundLimit?: InputMaybe<Scalars['Int']['input']>;
     /** The conversation strategy type. */
     type?: InputMaybe<ConversationStrategyTypes>;
 };
@@ -40284,6 +40302,9 @@ export type GetSpecificationQuery = {
             factExtractionLimit?: number | null;
             messagesWeight?: number | null;
             contentsWeight?: number | null;
+            toolResultTokenLimit?: number | null;
+            toolRoundLimit?: number | null;
+            toolBudgetThreshold?: number | null;
         } | null;
         promptStrategy?: {
             __typename?: 'PromptStrategy';
@@ -40726,6 +40747,9 @@ export type QuerySpecificationsQuery = {
                 factExtractionLimit?: number | null;
                 messagesWeight?: number | null;
                 contentsWeight?: number | null;
+                toolResultTokenLimit?: number | null;
+                toolRoundLimit?: number | null;
+                toolBudgetThreshold?: number | null;
             } | null;
             promptStrategy?: {
                 __typename?: 'PromptStrategy';

package/dist/helpers/context-management.d.ts

@@ -0,0 +1,91 @@
+import * as Types from "../generated/graphql-types.js";
+/** Returns `true` when js-tiktoken is installed and the encoder loaded successfully. */
+export declare function isAccurateTokenCounting(): boolean;
+/**
+ * Token estimation.
+ *
+ * When js-tiktoken is installed, returns an accurate BPE token count (o200k_base encoding).
+ * Otherwise falls back to a conservative heuristic: chars / 3.5.
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Configuration for context window management during agentic tool loops.
+ * Values can be provided by the server (via ConversationStrategy) or set client-side.
+ */
+export interface ContextStrategyConfig {
+    /** Max tokens for any single tool result. Results exceeding this are truncated. Default: 8192 */
+    toolResultTokenLimit: number;
+    /** Max tool call/response rounds to keep in context. Older rounds are dropped FIFO. Default: 10 */
+    toolRoundLimit: number;
+    /** Fraction of token budget at which client-side windowing is triggered. Default: 0.75 */
+    rebudgetThreshold: number;
+}
+export declare const DEFAULT_CONTEXT_STRATEGY: ContextStrategyConfig;
+/**
+ * Tracks token budget during streaming agent tool loops.
+ *
+ * Initialized from server-provided accurate token counts (via formatConversation details),
+ * then uses character-based heuristic estimation for incremental additions during the loop.
+ */
+export declare class TokenBudgetTracker {
+    private readonly tokenLimit;
+    private readonly completionTokenLimit;
+    private _usedTokens;
+    constructor(tokenLimit: number, completionTokenLimit: number, initialUsedTokens: number);
+    /**
+     * Create a tracker from formatConversation response details.
+     * Returns undefined if the details lack token information.
+     */
+    static fromDetails(details: {
+        tokenLimit?: number | null;
+        completionTokenLimit?: number | null;
+        messages?: Array<{
+            tokens?: number | null;
+        } | null> | null;
+    }): TokenBudgetTracker | undefined;
+    /** Total available token budget (tokenLimit - completionTokenLimit, at 95% ceiling) */
+    get budget(): number;
+    /** Current estimated token usage */
+    get usedTokens(): number;
+    /** Remaining tokens before budget is exhausted */
+    get remaining(): number;
+    /** Current usage as a percentage (0-100) */
+    get usagePercent(): number;
+    /** Model's full context token limit */
+    get maxTokens(): number;
+    /** Track addition of new message content */
+    addMessage(text: string, serverTokenCount?: number): void;
+    /** Check if we need to trigger windowing/re-budgeting */
+    needsRebudget(threshold: number): boolean;
+    /** Reset tracker from a fresh set of messages (after windowing) */
+    resetFromMessages(messages: Array<{
+        message?: string | null;
+        tokens?: number | null;
+    }>): void;
+    /** Get current usage snapshot for emitting events */
+    getUsageSnapshot(): {
+        usedTokens: number;
+        maxTokens: number;
+        percentage: number;
+        remainingTokens: number;
+    };
+}
+/**
+ * Truncates a tool result to fit within a token budget.
+ *
+ * Attempts to find a clean break point (JSON boundary or newline).
+ * Appends a [truncated] marker so the LLM knows data was cut.
+ */
+export declare function truncateToolResult(result: unknown, maxTokens: number, toolName: string): string;
+/**
+ * Windows tool rounds to keep the messages array within budget.
+ *
+ * Preserves:
+ * - "Header" messages (system prompt, conversation history, initial user message)
+ * - The most recent `keepRounds` tool rounds
+ *
+ * Drops older tool rounds and inserts a system message noting what was removed.
+ *
+ * @returns The windowed messages array
+ */
+export declare function windowToolRounds(messages: Types.ConversationMessage[], keepRounds: number): Types.ConversationMessage[];

package/dist/helpers/context-management.js

@@ -0,0 +1,223 @@
+import { createRequire } from "node:module";
+import * as Types from "../generated/graphql-types.js";
+// ── Singleton tiktoken encoder (best-effort load) ───────────────────────────
+let encoder;
+try {
+    const require = createRequire(import.meta.url);
+    const { Tiktoken } = require("js-tiktoken/lite");
+    const ranks = require("js-tiktoken/ranks/o200k_base");
+    encoder = new Tiktoken(ranks);
+    if (process.env.DEBUG_GRAPHLIT_SDK_INITIALIZATION) {
+        console.debug("[graphlit-sdk] tiktoken encoder loaded (o200k_base) — accurate token counting enabled");
+    }
+}
+catch {
+    // js-tiktoken not installed — fall back to heuristic
+    if (process.env.DEBUG_GRAPHLIT_SDK_INITIALIZATION) {
+        console.debug("[graphlit-sdk] js-tiktoken not available — using heuristic token estimation (chars / 3.5)");
+    }
+}
+/** Returns `true` when js-tiktoken is installed and the encoder loaded successfully. */
+export function isAccurateTokenCounting() {
+    return encoder !== undefined;
+}
+/**
+ * Token estimation.
+ *
+ * When js-tiktoken is installed, returns an accurate BPE token count (o200k_base encoding).
+ * Otherwise falls back to a conservative heuristic: chars / 3.5.
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    if (encoder)
+        return encoder.encode(text).length;
+    return Math.ceil(text.length / 3.5);
+}
+export const DEFAULT_CONTEXT_STRATEGY = {
+    toolResultTokenLimit: 8192,
+    toolRoundLimit: 10,
+    rebudgetThreshold: 0.75,
+};
+/**
+ * Tracks token budget during streaming agent tool loops.
+ *
+ * Initialized from server-provided accurate token counts (via formatConversation details),
+ * then uses character-based heuristic estimation for incremental additions during the loop.
+ */
+export class TokenBudgetTracker {
+    tokenLimit;
+    completionTokenLimit;
+    _usedTokens;
+    constructor(tokenLimit, completionTokenLimit, initialUsedTokens) {
+        this.tokenLimit = tokenLimit;
+        this.completionTokenLimit = completionTokenLimit;
+        this._usedTokens = initialUsedTokens;
+    }
+    /**
+     * Create a tracker from formatConversation response details.
+     * Returns undefined if the details lack token information.
+     */
+    static fromDetails(details) {
+        if (!details.tokenLimit)
+            return undefined;
+        const tokenLimit = details.tokenLimit;
+        const completionTokenLimit = details.completionTokenLimit ?? 4096;
+        const usedTokens = details.messages?.reduce((sum, msg) => sum + (msg?.tokens ?? 0), 0) ?? 0;
+        return new TokenBudgetTracker(tokenLimit, completionTokenLimit, usedTokens);
+    }
+    /** Total available token budget (tokenLimit - completionTokenLimit, at 95% ceiling) */
+    get budget() {
+        return Math.floor((this.tokenLimit - this.completionTokenLimit) * 0.95);
+    }
+    /** Current estimated token usage */
+    get usedTokens() {
+        return this._usedTokens;
+    }
+    /** Remaining tokens before budget is exhausted */
+    get remaining() {
+        return Math.max(0, this.budget - this._usedTokens);
+    }
+    /** Current usage as a percentage (0-100) */
+    get usagePercent() {
+        if (this.budget <= 0)
+            return 100;
+        return Math.round((this._usedTokens / this.budget) * 100);
+    }
+    /** Model's full context token limit */
+    get maxTokens() {
+        return this.tokenLimit;
+    }
+    /** Track addition of new message content */
+    addMessage(text, serverTokenCount) {
+        this._usedTokens += serverTokenCount ?? estimateTokens(text);
+    }
+    /** Check if we need to trigger windowing/re-budgeting */
+    needsRebudget(threshold) {
+        return this.usagePercent >= threshold * 100;
+    }
+    /** Reset tracker from a fresh set of messages (after windowing) */
+    resetFromMessages(messages) {
+        this._usedTokens = messages.reduce((sum, msg) => {
+            if (msg.tokens)
+                return sum + msg.tokens;
+            return sum + estimateTokens(msg.message ?? "");
+        }, 0);
+    }
+    /** Get current usage snapshot for emitting events */
+    getUsageSnapshot() {
+        return {
+            usedTokens: this._usedTokens,
+            maxTokens: this.tokenLimit,
+            percentage: this.usagePercent,
+            remainingTokens: this.remaining,
+        };
+    }
+}
+/**
+ * Truncates a tool result to fit within a token budget.
+ *
+ * Attempts to find a clean break point (JSON boundary or newline).
+ * Appends a [truncated] marker so the LLM knows data was cut.
+ */
+export function truncateToolResult(result, maxTokens, toolName) {
+    const text = typeof result === "string" ? result : JSON.stringify(result);
+    if (!text)
+        return "";
+    const estimatedTokens = estimateTokens(text);
+    if (estimatedTokens <= maxTokens)
+        return text;
+    // When tiktoken is available, compute the actual chars-per-token ratio for
+    // this specific text instead of using the hardcoded 3.5 heuristic.
+    const charsPerToken = encoder && estimatedTokens > 0
+        ? text.length / estimatedTokens
+        : 3.5;
+    const maxChars = Math.floor(maxTokens * charsPerToken);
+    let truncated = text.substring(0, maxChars);
+    // Try to find a clean break point
+    if (text.startsWith("{") || text.startsWith("[")) {
+        // For JSON, try to close at a valid boundary
+        const lastComplete = Math.max(truncated.lastIndexOf("},"), truncated.lastIndexOf("}\n"), truncated.lastIndexOf("],"), truncated.lastIndexOf("]\n"));
+        if (lastComplete > maxChars * 0.5) {
+            truncated = truncated.substring(0, lastComplete + 1);
+        }
+    }
+    else {
+        // For plain text, break at newline
+        const lastNewline = truncated.lastIndexOf("\n");
+        if (lastNewline > maxChars * 0.5) {
+            truncated = truncated.substring(0, lastNewline);
+        }
+    }
+    const truncatedTokens = estimateTokens(truncated);
+    return `${truncated}\n\n[truncated by ${toolName}: original ~${estimatedTokens} tokens, showing first ~${truncatedTokens} tokens]`;
+}
+/**
+ * Identifies the boundary between "header" messages (system prompt, conversation history,
+ * initial user message) and "tool round" messages (assistant+tool pairs from the agentic loop).
+ *
+ * Tool rounds start at the first assistant message that has tool calls.
+ */
+function findToolRoundStart(messages) {
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg.role === Types.ConversationRoleTypes.Assistant &&
+            msg.toolCalls &&
+            msg.toolCalls.length > 0) {
+            return i;
+        }
+    }
+    return messages.length; // No tool rounds found
+}
+/**
+ * Groups tool-round messages into logical rounds.
+ * Each round = one assistant message (with tool calls) + all subsequent tool response messages.
+ */
+function groupToolRounds(toolMessages) {
+    const rounds = [];
+    let currentRound = [];
+    for (const msg of toolMessages) {
+        if (msg.role === Types.ConversationRoleTypes.Assistant &&
+            currentRound.length > 0) {
+            // New assistant message starts a new round
+            rounds.push(currentRound);
+            currentRound = [msg];
+        }
+        else {
+            currentRound.push(msg);
+        }
+    }
+    if (currentRound.length > 0) {
+        rounds.push(currentRound);
+    }
+    return rounds;
+}
+/**
+ * Windows tool rounds to keep the messages array within budget.
+ *
+ * Preserves:
+ * - "Header" messages (system prompt, conversation history, initial user message)
+ * - The most recent `keepRounds` tool rounds
+ *
+ * Drops older tool rounds and inserts a system message noting what was removed.
+ *
+ * @returns The windowed messages array
+ */
+export function windowToolRounds(messages, keepRounds) {
+    const headerEnd = findToolRoundStart(messages);
+    const header = messages.slice(0, headerEnd);
+    const toolMessages = messages.slice(headerEnd);
+    const rounds = groupToolRounds(toolMessages);
+    if (rounds.length <= keepRounds)
+        return messages;
+    const keptRounds = rounds.slice(-keepRounds);
+    const droppedCount = rounds.length - keepRounds;
+    // Summary marker so the LLM knows context was trimmed
+    const summaryMessage = {
+        __typename: "ConversationMessage",
+        role: Types.ConversationRoleTypes.System,
+        message: `[Context management: ${droppedCount} earlier tool calling round(s) were removed to stay within token limits. The most recent ${keepRounds} round(s) are preserved below.]`,
+        timestamp: new Date().toISOString(),
+    };
+    return [...header, summaryMessage, ...keptRounds.flat()];
+}

package/dist/streaming/ui-event-adapter.d.ts

@@ -62,6 +62,7 @@ export declare class UIEventAdapter {
     private emitMessageUpdate;
     private emitUIEvent;
     private handleContextWindow;
+    private handleContextManagement;
     private handleReasoningStart;
     private handleReasoningDelta;
     private handleReasoningEnd;

package/dist/streaming/ui-event-adapter.js

@@ -81,6 +81,9 @@ export class UIEventAdapter {
             case "context_window":
                 this.handleContextWindow(event.usage);
                 break;
+            case "context_management":
+                this.handleContextManagement(event);
+                break;
             case "reasoning_start":
                 this.handleReasoningStart(event.format);
                 break;
@@ -611,6 +614,17 @@ export class UIEventAdapter {
             timestamp: new Date(),
         });
     }
+    handleContextManagement(event) {
+        if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING) {
+            console.log(`📊 [UIEventAdapter] Context management: ${event.action.type}`);
+        }
+        this.emitUIEvent({
+            type: "context_management",
+            action: event.action,
+            usage: event.usage,
+            timestamp: event.timestamp,
+        });
+    }
     handleReasoningStart(format) {
         if (process.env.DEBUG_GRAPHLIT_SDK_STREAMING) {
             console.log(`🤔 [UIEventAdapter] Reasoning start - Format: ${format}`);

package/dist/types/agent.d.ts

@@ -8,9 +8,18 @@ export interface ArtifactCollector {
     }[]>;
 }
 export type ToolHandler = (args: any, artifacts?: ArtifactCollector) => Promise<any>;
+export interface ContextStrategy {
+    /** Max tokens for any single tool result. Results exceeding this are truncated. Default: 8192 */
+    toolResultTokenLimit?: number;
+    /** Max tool call/response rounds to keep in context. Older rounds are dropped FIFO. Default: 10 */
+    toolRoundLimit?: number;
+    /** Fraction of token budget (0.0-1.0) at which client-side windowing is triggered. Default: 0.75 */
+    rebudgetThreshold?: number;
+}
 export interface AgentOptions {
     maxToolRounds?: number;
     timeout?: number;
+    contextStrategy?: ContextStrategy;
 }
 export interface AgentMetrics {
     totalTime: number;
@@ -27,6 +36,16 @@ export interface ContextWindowUsage {
     percentage: number;
     remainingTokens: number;
 }
+export type ContextManagementAction = {
+    type: "truncated_tool_result";
+    toolName: string;
+    originalTokens: number;
+    truncatedTokens: number;
+} | {
+    type: "windowed_tool_rounds";
+    droppedRounds: number;
+    keptRounds: number;
+};
 export interface AgentResult {
     message: string;
     conversationId: string;
@@ -36,6 +55,7 @@ export interface AgentResult {
     metrics?: AgentMetrics;
     usage?: UsageInfo;
     contextWindow?: ContextWindowUsage;
+    contextActions?: ContextManagementAction[];
     error?: AgentError;
 }
 export interface StreamAgentOptions {
@@ -44,6 +64,7 @@ export interface StreamAgentOptions {
     smoothingEnabled?: boolean;
     chunkingStrategy?: "character" | "word" | "sentence";
     smoothingDelay?: number;
+    contextStrategy?: ContextStrategy;
 }
 export interface ToolCallResult {
     id: string;

package/dist/types/internal.d.ts

@@ -2,6 +2,7 @@
  * Internal types used by the streaming implementation
  * These are not exported to consumers of the library
  */
+import { ContextManagementAction } from "./agent.js";
 /**
  * Low-level streaming events used internally by providers
  * These get transformed into AgentStreamEvent by UIEventAdapter
@@ -64,6 +65,16 @@ export type StreamEvent = {
         percentage: number;
         remainingTokens: number;
     };
+} | {
+    type: "context_management";
+    action: ContextManagementAction;
+    usage: {
+        usedTokens: number;
+        maxTokens: number;
+        percentage: number;
+        remainingTokens: number;
+    };
+    timestamp: Date;
 } | {
     type: "reasoning_start";
     format: "thinking_tag" | "markdown" | "custom";

package/dist/types/ui-events.d.ts

@@ -1,4 +1,5 @@
 import { ConversationMessage, ConversationToolCall } from "../generated/graphql-types.js";
+import { ContextManagementAction } from "./agent.js";
 /**
  * Tool execution status for streaming
  */
@@ -44,6 +45,16 @@ export type AgentStreamEvent = {
     conversationId: string;
     timestamp: Date;
 } | ContextWindowEvent | {
+    type: "context_management";
+    action: ContextManagementAction;
+    usage: {
+        usedTokens: number;
+        maxTokens: number;
+        percentage: number;
+        remainingTokens: number;
+    };
+    timestamp: Date;
+} | {
     type: "message_update";
     message: StreamingConversationMessage;
     isStreaming: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphlit-client",
-  "version": "1.0.20260217005",
+  "version": "1.0.20260218002",
   "description": "Graphlit API Client for TypeScript",
   "type": "module",
   "main": "./dist/client.js",
@@ -73,6 +73,9 @@
     },
     "@aws-sdk/client-bedrock-runtime": {
       "optional": true
+    },
+    "js-tiktoken": {
+      "optional": true
     }
   },
   "optionalDependencies": {
@@ -81,6 +84,7 @@
     "@mistralai/mistralai": "^1.11.0",
     "cohere-ai": "^7.20.0",
     "groq-sdk": "^0.25.0",
+    "js-tiktoken": "^1.0.16",
     "openai": "^5.3.0"
   },
   "devDependencies": {