toolpack-sdk 3.3.0 → 3.4.0

package/dist/index.d.cts

@@ -252,9 +252,21 @@ interface ToolpackCredentials {
     /** Netlify auth token. Fallback: NETLIFY_AUTH_TOKEN */
     netlifyAuthToken?: string;
 }
+/**
+ * Who a run acts for, e.g. the signed-in user of the host application.
+ * Supplied by the host (never by the model), so a tool can trust it for per-user data.
+ */
+interface ToolActor {
+    /** The host application's stable id for the actor. */
+    id: string;
+    /** What the actor is, in the host's terms (e.g. 'user'). */
+    kind?: string;
+}
 interface ToolContext {
     /** Absolute path to the workspace/project root */
     workspaceRoot: string;
+    /** Who this run acts for, when the host set one (see ToolpackInitConfig.actor). */
+    actor?: ToolActor;
     /**
      * Tool-specific config from toolsConfig.additionalConfigurations.
      * Includes credentials (ctx.config.credentials) and per-tool settings
@@ -1377,6 +1389,8 @@ interface AIClientConfig {
     toolsConfig?: ToolsConfig;
     systemPrompt?: string;
     disableBaseContext?: boolean;
+    /** Disable automatic tool usage guidance injection into the system prompt */
+    disableToolGuidance?: boolean;
     /** Human-in-the-loop configuration for tool confirmation */
     hitlConfig?: HitlConfig;
     /** Callback for handling tool confirmation requests */
@@ -1385,6 +1399,8 @@ interface AIClientConfig {
     conversationId?: string;
     /** Context window management configuration */
     contextWindowConfig?: ContextWindowConfig;
+    /** Who tool calls act for; passed to every tool as `ctx.actor`. A function is read on each call. */
+    actor?: ToolActor | (() => ToolActor | null | undefined);
 }
 declare class AIClient extends EventEmitter {
     private providers;
@@ -1398,11 +1414,13 @@ declare class AIClient extends EventEmitter {
     private activeMode;
     private overrideSystemPrompt?;
     private disableBaseContext;
+    private disableToolGuidance;
     private toolResultMaxChars;
     private hitlConfig?;
     private onToolConfirm?;
     private conversationId?;
     private contextWindowConfig?;
+    private actor?;
     private contextWindowStateManager?;
     private providerModelCache;
     private ruleLoader;
@@ -1488,13 +1506,17 @@ declare class AIClient extends EventEmitter {
      * When tools are enabled and autoExecute is true, handles the full
      * tool call → execute → send result → get final answer loop.
      */
-    generate<T = unknown>(request: CompletionRequest<T>, providerName?: string): Promise<CompletionResponse<T>>;
+    generate<T = unknown>(request: CompletionRequest<T>, providerName?: string, options?: {
+        getLatestRequestTools?: () => RequestToolDefinition[];
+    }): Promise<CompletionResponse<T>>;
     /**
      * unified stream completion
      * When tools are enabled and autoExecute is true, handles tool calls
      * by collecting them, executing, and re-calling the model.
      */
-    stream(request: CompletionRequest, providerName?: string): AsyncGenerator<CompletionChunk>;
+    stream(request: CompletionRequest, providerName?: string, options?: {
+        getLatestRequestTools?: () => RequestToolDefinition[];
+    }): AsyncGenerator<CompletionChunk>;
     /**
      * unified embed
      */
@@ -1690,6 +1712,8 @@ declare class VertexAIAdapter extends ProviderAdapter {
 
 declare class GeminiAdapter extends ProviderAdapter {
     private genAI;
+    private readonly rawContentCache;
+    private static readonly RAW_CONTENT_CACHE_MAX;
     constructor(apiKey: string);
     supportsFileUpload(): boolean;
     /**
@@ -1920,6 +1944,12 @@ declare function fetchUrlAsBase64(url: string): Promise<{
     data: string;
     mimeType: string;
 }>;
+interface FileEnvelope {
+    type: 'file';
+    mimeType: string;
+    url: string;
+}
+declare function parseFileEnvelope(content: string): FileEnvelope | null;
 declare function normalizeImagePart(part: ImagePart): Promise<{
     data: string;
     mimeType: string;
@@ -3192,6 +3222,8 @@ interface ToolpackInitConfig {
     customProviders?: ProviderAdapter[] | Record<string, ProviderAdapter>;
     /** Disable base agent context injection (for testing or custom prompts) */
     disableBaseContext?: boolean;
+    /** Disable automatic tool usage guidance injection into the system prompt */
+    disableToolGuidance?: boolean;
     mcp?: McpToolsConfig;
     /**
      * Optional Knowledge instance for RAG (Retrieval-Augmented Generation).
@@ -3218,6 +3250,12 @@ interface ToolpackInitConfig {
     }) => Promise<ConfirmationDecision>;
     /** Optional conversation ID for tracking context across confirmations */
     conversationId?: string;
+    /**
+     * Who this instance's tool calls act for (e.g. the signed-in user). Passed to every tool as
+     * `ctx.actor`; the model never sees or sets it. Pass a function when one instance serves
+     * several actors: it is read on each tool call.
+     */
+    actor?: ToolActor | (() => ToolActor | null | undefined);
     /**
      * Optional interceptors that wrap each `generate()` call in the direct execution path.
      * Each interceptor receives the full CompletionRequest and a `next()` function.
@@ -4032,4 +4070,4 @@ declare class RuleLoader {
     private readFile;
 }
 
-export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, AnthropicVertexAdapter, type AnthropicVertexConfig, type AssembledPrompt, type AssemblerOptions, AuthenticationError, BM25Engine, BM25SearchEngine, type BM25SearchResult, BUILT_IN_MODES, type BypassRuleType, CHAT_MODE, CHAT_WORKFLOW, CODING_MODE, CODING_PLANNING_PROMPT, CODING_WORKFLOW, CONFIG_DIR_NAME, CONFIG_FILE_NAME, type CompletionChunk, type CompletionOptions, type CompletionRequest, type CompletionResponse, type ConfirmationDecision, type ConfirmationLevel$1 as ConfirmationLevel, ConnectionError, type ContextPrunedEvent, type ContextWindowConfig, ContextWindowConfigError, ContextWindowExceededError, type ContextWindowExceededEvent, type ContextWindowState, ContextWindowStateManager, type ContextWindowStrategy, type ContextWindowWarningEvent, ConversationNotFoundError, type ConversationScope, type ConversationSearchOptions, type ConversationStore, type ConversationSummarizedEvent, DEFAULT_MODE_NAME, DEFAULT_TOOLS_CONFIG, DEFAULT_TOOL_SEARCH_CONFIG, DEFAULT_WORKFLOW, DEFAULT_WORKFLOW_CONFIG, type EmbeddingRequest, type EmbeddingResponse, FILE_LIMITS, type FilePart, type FileUploadRequest, type FileUploadResponse, GeminiAdapter, type GetOptions, type HitlConfig, type ImageDataPart, type ImageFilePart, type ImagePart, type ImageUrlPart, InMemoryConversationStore, type InMemoryConversationStoreConfig, InsufficientContextError, InvalidRequestError, type JsonRpcRequest, type JsonRpcResponse, type KnowledgeInstance, type McpAgentDefinition, type McpAuthConfig, McpClient, type McpClientConfig, McpConnectionError, type McpCustomAuthConfig, type McpJwtAuthConfig, type McpServerCapabilities, type McpServerConfig, type McpServerExposeConfig, type McpServerHandle, type McpStaticAuthConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type McpTransport, type MediaOptions, type MediaUploadStrategy, type Message, type MessageContent, type ModeBlockedHint, type ModeConfig, ModeRegistry, OllamaAdapter, type OllamaAdapterConfig, type OllamaModelInfo, OllamaProvider, type OllamaProviderEntry, type OnToolConfirmCallback, OpenAIAdapter, OpenRouterAdapter, type OpenRouterOptions, PageError, type Participant, type Plan, type PlanStep, Planner, type PromptMessage, ProviderAdapter, type ProviderConfig, ProviderError, type ProviderInfo, type ProviderModelInfo, type ProviderOptions, type PruneResult, RateLimitError, type RequestToolDefinition, type Role, RuleLoader, type RuntimeConfigStatus, SDKError, SQLiteConversationStore, type SQLiteConversationStoreConfig, type SearchHistoryEntry, type SearchOptions, type SearchResult, type Skill, type SkillSection, type SkillToolsOptions, type SkillValidationMode, type SlmModelEntry, type StoredMessage, SummarizationError, type SummarizationOptions, type SummarizationResult, TOOLPACK_DIR_NAME, TOOL_SEARCH_NAME, type TextPart, TimeoutError, type ToolAnnotations, type ToolCall, type ToolCallFunction, type ToolCallMessage, type ToolCallRequest, type ToolCallResult, type ToolCategory, type ToolConfirmation, type ToolConfirmationRequestedEvent, type ToolConfirmationResolvedEvent, type ToolContext, type ToolDefinition, ToolDiscoveryCache, type ToolLogEvent, type ToolParameterProperty, type ToolParameters, type ToolProgressEvent, type ToolProject, type ToolProjectDependencies, type ToolProjectManifest, ToolRegistry, type ToolResult, ToolRouter, type ToolSchema, type ToolSearchConfig, Toolpack, type ToolpackConfig, type ToolpackCredentials, type ToolpackInitConfig, type ToolpackInterceptor, type ToolpackMcpServerConfig, type ToolpackNextFunction, type ToolsConfig, type Usage, VertexAIAdapter, type VertexAIConfig, type WorkflowConfig, type WorkflowEvents, WorkflowExecutor, type WorkflowProgress, type WorkflowResult, addBypassRule, buildSummarizedHistory, cloudDeployTool, cloudListTool, cloudStatusTool, cloudToolsProject, codingExtractFunctionTool, codingFindReferencesTool, codingFindSymbolTool, codingGetCallHierarchyTool, codingGetDiagnosticsTool, codingGetExportsTool, codingGetImportsTool, codingGetOutlineTool, codingGetSymbolsTool, codingGoToDefinitionTool, codingMultiFileEditTool, codingRefactorRenameTool, codingToolsProject, countTokens, createContextWindowStateManager, createMcpToolProject, createMode, createSkillTools, createSummarizationReport, createSummarySystemMessage, createToolProject, dbCountTool, dbDeleteTool, dbInsertTool, dbQueryTool, dbSchemaTool, dbTablesTool, dbToolsProject, dbUpdateTool, diffApplyTool, diffCreateTool, diffPreviewTool, diffToolsProject, disconnectMcpToolProject, ensureGlobalConfigDir, ensureLocalConfigDir, estimateSummaryTokens, estimateTokenCount, execKillTool, execListProcessesTool, execReadOutputTool, execRunBackgroundTool, execRunBlockingTool, execRunShellTool, execRunTool, execTailOutputTool, execToolsProject, extractConversationKeypoints, fetchUrlAsBase64, fsAppendFileTool, fsBatchReadTool, fsBatchWriteTool, fsCopyTool, fsCreateDirTool, fsDeleteDirTool, fsDeleteFileTool, fsExistsTool, fsGlobTool, fsListDirTool, fsMoveTool, fsReadFileRangeTool, fsReadFileTool, fsReplaceInFileTool, fsSearchTool, fsStatTool, fsToolsProject, fsTreeTool, fsWriteFileTool, generateSummarizationPrompt, generateToolCategoriesPrompt, getContextWindowPercentage, getDefaultSlmModel, getGlobalConfigDir, getGlobalConfigPath, getGlobalToolpackDir, getLocalConfigDir, getLocalConfigPath, getLocalToolpackDir, getMessageStats, getMimeType, getOllamaBaseUrl, getOllamaProviderEntries, getRegisteredSlmModels, getRuntimeConfigStatus, getSafeOutputReserve, getToolSearchSchema, getToolpackConfig, getUserHomeDir, gitAddTool, gitBlameTool, gitBranchCreateTool, gitBranchListTool, gitCheckoutTool, gitCloneTool, gitCommitTool, gitDiffTool, gitLogTool, gitStatusTool, gitToolsProject, githubContentsGetTextTool, githubGraphqlExecuteTool, githubIssuesCommentsCreateTool, githubPrDiffGetTool, githubPrFilesListTool, githubPrReviewCommentsReplyTool, githubPrReviewThreadsListTool, githubPrReviewThreadsResolveTool, githubPrReviewsSubmitTool, githubToolsProject, groupMessagesByRole, handleContextWindowError, httpDeleteTool, httpDownloadTool, httpGetTool, httpPostTool, httpPutTool, httpToolsProject, initializeGlobalConfigIfFirstRun, isContextWindowError, isDataUri, isRegisteredSlm, isToolSearchTool, k8sApplyManifestTool, k8sDeleteResourceTool, k8sDescribeTool, k8sGetConfigMapTool, k8sGetLogsTool, k8sGetNamespacesTool, k8sListDeploymentsTool, k8sListPodsTool, k8sListServicesTool, k8sSwitchContextTool, k8sToolsProject, k8sWaitForDeploymentTool, loadFullConfig, loadRuntimeConfig, loadToolsConfig, mergeSummarizationResults, normalizeImagePart, ollamaRequest, ollamaStream, parseDataUri, parseSkillFile, parseSummarizationResponse, prepareSummarizationRequest, pruneMessages, readFileAsBase64, reloadToolpackConfig, removeBypassRule, saveToolsConfig, slackAuthTestTool, slackChatPostEphemeralTool, slackChatPostMessageTool, slackConversationsHistoryTool, slackConversationsRepliesTool, slackReactionsAddTool, slackToolsProject, systemCwdTool, systemDiskUsageTool, systemEnvTool, systemInfoTool, systemSetEnvTool, systemToolsProject, toDataUri, toolSearchDefinition, truncateMessage, validateSummarizationResult, webExtractLinksTool, webFeedTool, webFetchTool, webMapTool, webMetadataTool, webScrapeTool, webScreenshotTool, webSearchTool, webSitemapTool, webToolsProject, wouldExceedContextWindow };
+export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, AnthropicVertexAdapter, type AnthropicVertexConfig, type AssembledPrompt, type AssemblerOptions, AuthenticationError, BM25Engine, BM25SearchEngine, type BM25SearchResult, BUILT_IN_MODES, type BypassRuleType, CHAT_MODE, CHAT_WORKFLOW, CODING_MODE, CODING_PLANNING_PROMPT, CODING_WORKFLOW, CONFIG_DIR_NAME, CONFIG_FILE_NAME, type CompletionChunk, type CompletionOptions, type CompletionRequest, type CompletionResponse, type ConfirmationDecision, type ConfirmationLevel$1 as ConfirmationLevel, ConnectionError, type ContextPrunedEvent, type ContextWindowConfig, ContextWindowConfigError, ContextWindowExceededError, type ContextWindowExceededEvent, type ContextWindowState, ContextWindowStateManager, type ContextWindowStrategy, type ContextWindowWarningEvent, ConversationNotFoundError, type ConversationScope, type ConversationSearchOptions, type ConversationStore, type ConversationSummarizedEvent, DEFAULT_MODE_NAME, DEFAULT_TOOLS_CONFIG, DEFAULT_TOOL_SEARCH_CONFIG, DEFAULT_WORKFLOW, DEFAULT_WORKFLOW_CONFIG, type EmbeddingRequest, type EmbeddingResponse, FILE_LIMITS, type FileEnvelope, type FilePart, type FileUploadRequest, type FileUploadResponse, GeminiAdapter, type GetOptions, type HitlConfig, type ImageDataPart, type ImageFilePart, type ImagePart, type ImageUrlPart, InMemoryConversationStore, type InMemoryConversationStoreConfig, InsufficientContextError, InvalidRequestError, type JsonRpcRequest, type JsonRpcResponse, type KnowledgeInstance, type McpAgentDefinition, type McpAuthConfig, McpClient, type McpClientConfig, McpConnectionError, type McpCustomAuthConfig, type McpJwtAuthConfig, type McpServerCapabilities, type McpServerConfig, type McpServerExposeConfig, type McpServerHandle, type McpStaticAuthConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type McpTransport, type MediaOptions, type MediaUploadStrategy, type Message, type MessageContent, type ModeBlockedHint, type ModeConfig, ModeRegistry, OllamaAdapter, type OllamaAdapterConfig, type OllamaModelInfo, OllamaProvider, type OllamaProviderEntry, type OnToolConfirmCallback, OpenAIAdapter, OpenRouterAdapter, type OpenRouterOptions, PageError, type Participant, type Plan, type PlanStep, Planner, type PromptMessage, ProviderAdapter, type ProviderConfig, ProviderError, type ProviderInfo, type ProviderModelInfo, type ProviderOptions, type PruneResult, RateLimitError, type RequestToolDefinition, type Role, RuleLoader, type RuntimeConfigStatus, SDKError, SQLiteConversationStore, type SQLiteConversationStoreConfig, type SearchHistoryEntry, type SearchOptions, type SearchResult, type Skill, type SkillSection, type SkillToolsOptions, type SkillValidationMode, type SlmModelEntry, type StoredMessage, SummarizationError, type SummarizationOptions, type SummarizationResult, TOOLPACK_DIR_NAME, TOOL_SEARCH_NAME, type TextPart, TimeoutError, type ToolActor, type ToolAnnotations, type ToolCall, type ToolCallFunction, type ToolCallMessage, type ToolCallRequest, type ToolCallResult, type ToolCategory, type ToolConfirmation, type ToolConfirmationRequestedEvent, type ToolConfirmationResolvedEvent, type ToolContext, type ToolDefinition, ToolDiscoveryCache, type ToolLogEvent, type ToolParameterProperty, type ToolParameters, type ToolProgressEvent, type ToolProject, type ToolProjectDependencies, type ToolProjectManifest, ToolRegistry, type ToolResult, ToolRouter, type ToolSchema, type ToolSearchConfig, Toolpack, type ToolpackConfig, type ToolpackCredentials, type ToolpackInitConfig, type ToolpackInterceptor, type ToolpackMcpServerConfig, type ToolpackNextFunction, type ToolsConfig, type Usage, VertexAIAdapter, type VertexAIConfig, type WorkflowConfig, type WorkflowEvents, WorkflowExecutor, type WorkflowProgress, type WorkflowResult, addBypassRule, buildSummarizedHistory, cloudDeployTool, cloudListTool, cloudStatusTool, cloudToolsProject, codingExtractFunctionTool, codingFindReferencesTool, codingFindSymbolTool, codingGetCallHierarchyTool, codingGetDiagnosticsTool, codingGetExportsTool, codingGetImportsTool, codingGetOutlineTool, codingGetSymbolsTool, codingGoToDefinitionTool, codingMultiFileEditTool, codingRefactorRenameTool, codingToolsProject, countTokens, createContextWindowStateManager, createMcpToolProject, createMode, createSkillTools, createSummarizationReport, createSummarySystemMessage, createToolProject, dbCountTool, dbDeleteTool, dbInsertTool, dbQueryTool, dbSchemaTool, dbTablesTool, dbToolsProject, dbUpdateTool, diffApplyTool, diffCreateTool, diffPreviewTool, diffToolsProject, disconnectMcpToolProject, ensureGlobalConfigDir, ensureLocalConfigDir, estimateSummaryTokens, estimateTokenCount, execKillTool, execListProcessesTool, execReadOutputTool, execRunBackgroundTool, execRunBlockingTool, execRunShellTool, execRunTool, execTailOutputTool, execToolsProject, extractConversationKeypoints, fetchUrlAsBase64, fsAppendFileTool, fsBatchReadTool, fsBatchWriteTool, fsCopyTool, fsCreateDirTool, fsDeleteDirTool, fsDeleteFileTool, fsExistsTool, fsGlobTool, fsListDirTool, fsMoveTool, fsReadFileRangeTool, fsReadFileTool, fsReplaceInFileTool, fsSearchTool, fsStatTool, fsToolsProject, fsTreeTool, fsWriteFileTool, generateSummarizationPrompt, generateToolCategoriesPrompt, getContextWindowPercentage, getDefaultSlmModel, getGlobalConfigDir, getGlobalConfigPath, getGlobalToolpackDir, getLocalConfigDir, getLocalConfigPath, getLocalToolpackDir, getMessageStats, getMimeType, getOllamaBaseUrl, getOllamaProviderEntries, getRegisteredSlmModels, getRuntimeConfigStatus, getSafeOutputReserve, getToolSearchSchema, getToolpackConfig, getUserHomeDir, gitAddTool, gitBlameTool, gitBranchCreateTool, gitBranchListTool, gitCheckoutTool, gitCloneTool, gitCommitTool, gitDiffTool, gitLogTool, gitStatusTool, gitToolsProject, githubContentsGetTextTool, githubGraphqlExecuteTool, githubIssuesCommentsCreateTool, githubPrDiffGetTool, githubPrFilesListTool, githubPrReviewCommentsReplyTool, githubPrReviewThreadsListTool, githubPrReviewThreadsResolveTool, githubPrReviewsSubmitTool, githubToolsProject, groupMessagesByRole, handleContextWindowError, httpDeleteTool, httpDownloadTool, httpGetTool, httpPostTool, httpPutTool, httpToolsProject, initializeGlobalConfigIfFirstRun, isContextWindowError, isDataUri, isRegisteredSlm, isToolSearchTool, k8sApplyManifestTool, k8sDeleteResourceTool, k8sDescribeTool, k8sGetConfigMapTool, k8sGetLogsTool, k8sGetNamespacesTool, k8sListDeploymentsTool, k8sListPodsTool, k8sListServicesTool, k8sSwitchContextTool, k8sToolsProject, k8sWaitForDeploymentTool, loadFullConfig, loadRuntimeConfig, loadToolsConfig, mergeSummarizationResults, normalizeImagePart, ollamaRequest, ollamaStream, parseDataUri, parseFileEnvelope, parseSkillFile, parseSummarizationResponse, prepareSummarizationRequest, pruneMessages, readFileAsBase64, reloadToolpackConfig, removeBypassRule, saveToolsConfig, slackAuthTestTool, slackChatPostEphemeralTool, slackChatPostMessageTool, slackConversationsHistoryTool, slackConversationsRepliesTool, slackReactionsAddTool, slackToolsProject, systemCwdTool, systemDiskUsageTool, systemEnvTool, systemInfoTool, systemSetEnvTool, systemToolsProject, toDataUri, toolSearchDefinition, truncateMessage, validateSummarizationResult, webExtractLinksTool, webFeedTool, webFetchTool, webMapTool, webMetadataTool, webScrapeTool, webScreenshotTool, webSearchTool, webSitemapTool, webToolsProject, wouldExceedContextWindow };

package/dist/index.d.ts

@@ -252,9 +252,21 @@ interface ToolpackCredentials {
     /** Netlify auth token. Fallback: NETLIFY_AUTH_TOKEN */
     netlifyAuthToken?: string;
 }
+/**
+ * Who a run acts for, e.g. the signed-in user of the host application.
+ * Supplied by the host (never by the model), so a tool can trust it for per-user data.
+ */
+interface ToolActor {
+    /** The host application's stable id for the actor. */
+    id: string;
+    /** What the actor is, in the host's terms (e.g. 'user'). */
+    kind?: string;
+}
 interface ToolContext {
     /** Absolute path to the workspace/project root */
     workspaceRoot: string;
+    /** Who this run acts for, when the host set one (see ToolpackInitConfig.actor). */
+    actor?: ToolActor;
     /**
      * Tool-specific config from toolsConfig.additionalConfigurations.
      * Includes credentials (ctx.config.credentials) and per-tool settings
@@ -1377,6 +1389,8 @@ interface AIClientConfig {
     toolsConfig?: ToolsConfig;
     systemPrompt?: string;
     disableBaseContext?: boolean;
+    /** Disable automatic tool usage guidance injection into the system prompt */
+    disableToolGuidance?: boolean;
     /** Human-in-the-loop configuration for tool confirmation */
     hitlConfig?: HitlConfig;
     /** Callback for handling tool confirmation requests */
@@ -1385,6 +1399,8 @@ interface AIClientConfig {
     conversationId?: string;
     /** Context window management configuration */
     contextWindowConfig?: ContextWindowConfig;
+    /** Who tool calls act for; passed to every tool as `ctx.actor`. A function is read on each call. */
+    actor?: ToolActor | (() => ToolActor | null | undefined);
 }
 declare class AIClient extends EventEmitter {
     private providers;
@@ -1398,11 +1414,13 @@ declare class AIClient extends EventEmitter {
     private activeMode;
     private overrideSystemPrompt?;
     private disableBaseContext;
+    private disableToolGuidance;
     private toolResultMaxChars;
     private hitlConfig?;
     private onToolConfirm?;
     private conversationId?;
     private contextWindowConfig?;
+    private actor?;
     private contextWindowStateManager?;
     private providerModelCache;
     private ruleLoader;
@@ -1488,13 +1506,17 @@ declare class AIClient extends EventEmitter {
      * When tools are enabled and autoExecute is true, handles the full
      * tool call → execute → send result → get final answer loop.
      */
-    generate<T = unknown>(request: CompletionRequest<T>, providerName?: string): Promise<CompletionResponse<T>>;
+    generate<T = unknown>(request: CompletionRequest<T>, providerName?: string, options?: {
+        getLatestRequestTools?: () => RequestToolDefinition[];
+    }): Promise<CompletionResponse<T>>;
     /**
      * unified stream completion
      * When tools are enabled and autoExecute is true, handles tool calls
      * by collecting them, executing, and re-calling the model.
      */
-    stream(request: CompletionRequest, providerName?: string): AsyncGenerator<CompletionChunk>;
+    stream(request: CompletionRequest, providerName?: string, options?: {
+        getLatestRequestTools?: () => RequestToolDefinition[];
+    }): AsyncGenerator<CompletionChunk>;
     /**
      * unified embed
      */
@@ -1690,6 +1712,8 @@ declare class VertexAIAdapter extends ProviderAdapter {
 
 declare class GeminiAdapter extends ProviderAdapter {
     private genAI;
+    private readonly rawContentCache;
+    private static readonly RAW_CONTENT_CACHE_MAX;
     constructor(apiKey: string);
     supportsFileUpload(): boolean;
     /**
@@ -1920,6 +1944,12 @@ declare function fetchUrlAsBase64(url: string): Promise<{
     data: string;
     mimeType: string;
 }>;
+interface FileEnvelope {
+    type: 'file';
+    mimeType: string;
+    url: string;
+}
+declare function parseFileEnvelope(content: string): FileEnvelope | null;
 declare function normalizeImagePart(part: ImagePart): Promise<{
     data: string;
     mimeType: string;
@@ -3192,6 +3222,8 @@ interface ToolpackInitConfig {
     customProviders?: ProviderAdapter[] | Record<string, ProviderAdapter>;
     /** Disable base agent context injection (for testing or custom prompts) */
     disableBaseContext?: boolean;
+    /** Disable automatic tool usage guidance injection into the system prompt */
+    disableToolGuidance?: boolean;
     mcp?: McpToolsConfig;
     /**
      * Optional Knowledge instance for RAG (Retrieval-Augmented Generation).
@@ -3218,6 +3250,12 @@ interface ToolpackInitConfig {
     }) => Promise<ConfirmationDecision>;
     /** Optional conversation ID for tracking context across confirmations */
     conversationId?: string;
+    /**
+     * Who this instance's tool calls act for (e.g. the signed-in user). Passed to every tool as
+     * `ctx.actor`; the model never sees or sets it. Pass a function when one instance serves
+     * several actors: it is read on each tool call.
+     */
+    actor?: ToolActor | (() => ToolActor | null | undefined);
     /**
      * Optional interceptors that wrap each `generate()` call in the direct execution path.
      * Each interceptor receives the full CompletionRequest and a `next()` function.
@@ -4032,4 +4070,4 @@ declare class RuleLoader {
     private readFile;
 }
 
-export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, AnthropicVertexAdapter, type AnthropicVertexConfig, type AssembledPrompt, type AssemblerOptions, AuthenticationError, BM25Engine, BM25SearchEngine, type BM25SearchResult, BUILT_IN_MODES, type BypassRuleType, CHAT_MODE, CHAT_WORKFLOW, CODING_MODE, CODING_PLANNING_PROMPT, CODING_WORKFLOW, CONFIG_DIR_NAME, CONFIG_FILE_NAME, type CompletionChunk, type CompletionOptions, type CompletionRequest, type CompletionResponse, type ConfirmationDecision, type ConfirmationLevel$1 as ConfirmationLevel, ConnectionError, type ContextPrunedEvent, type ContextWindowConfig, ContextWindowConfigError, ContextWindowExceededError, type ContextWindowExceededEvent, type ContextWindowState, ContextWindowStateManager, type ContextWindowStrategy, type ContextWindowWarningEvent, ConversationNotFoundError, type ConversationScope, type ConversationSearchOptions, type ConversationStore, type ConversationSummarizedEvent, DEFAULT_MODE_NAME, DEFAULT_TOOLS_CONFIG, DEFAULT_TOOL_SEARCH_CONFIG, DEFAULT_WORKFLOW, DEFAULT_WORKFLOW_CONFIG, type EmbeddingRequest, type EmbeddingResponse, FILE_LIMITS, type FilePart, type FileUploadRequest, type FileUploadResponse, GeminiAdapter, type GetOptions, type HitlConfig, type ImageDataPart, type ImageFilePart, type ImagePart, type ImageUrlPart, InMemoryConversationStore, type InMemoryConversationStoreConfig, InsufficientContextError, InvalidRequestError, type JsonRpcRequest, type JsonRpcResponse, type KnowledgeInstance, type McpAgentDefinition, type McpAuthConfig, McpClient, type McpClientConfig, McpConnectionError, type McpCustomAuthConfig, type McpJwtAuthConfig, type McpServerCapabilities, type McpServerConfig, type McpServerExposeConfig, type McpServerHandle, type McpStaticAuthConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type McpTransport, type MediaOptions, type MediaUploadStrategy, type Message, type MessageContent, type ModeBlockedHint, type ModeConfig, ModeRegistry, OllamaAdapter, type OllamaAdapterConfig, type OllamaModelInfo, OllamaProvider, type OllamaProviderEntry, type OnToolConfirmCallback, OpenAIAdapter, OpenRouterAdapter, type OpenRouterOptions, PageError, type Participant, type Plan, type PlanStep, Planner, type PromptMessage, ProviderAdapter, type ProviderConfig, ProviderError, type ProviderInfo, type ProviderModelInfo, type ProviderOptions, type PruneResult, RateLimitError, type RequestToolDefinition, type Role, RuleLoader, type RuntimeConfigStatus, SDKError, SQLiteConversationStore, type SQLiteConversationStoreConfig, type SearchHistoryEntry, type SearchOptions, type SearchResult, type Skill, type SkillSection, type SkillToolsOptions, type SkillValidationMode, type SlmModelEntry, type StoredMessage, SummarizationError, type SummarizationOptions, type SummarizationResult, TOOLPACK_DIR_NAME, TOOL_SEARCH_NAME, type TextPart, TimeoutError, type ToolAnnotations, type ToolCall, type ToolCallFunction, type ToolCallMessage, type ToolCallRequest, type ToolCallResult, type ToolCategory, type ToolConfirmation, type ToolConfirmationRequestedEvent, type ToolConfirmationResolvedEvent, type ToolContext, type ToolDefinition, ToolDiscoveryCache, type ToolLogEvent, type ToolParameterProperty, type ToolParameters, type ToolProgressEvent, type ToolProject, type ToolProjectDependencies, type ToolProjectManifest, ToolRegistry, type ToolResult, ToolRouter, type ToolSchema, type ToolSearchConfig, Toolpack, type ToolpackConfig, type ToolpackCredentials, type ToolpackInitConfig, type ToolpackInterceptor, type ToolpackMcpServerConfig, type ToolpackNextFunction, type ToolsConfig, type Usage, VertexAIAdapter, type VertexAIConfig, type WorkflowConfig, type WorkflowEvents, WorkflowExecutor, type WorkflowProgress, type WorkflowResult, addBypassRule, buildSummarizedHistory, cloudDeployTool, cloudListTool, cloudStatusTool, cloudToolsProject, codingExtractFunctionTool, codingFindReferencesTool, codingFindSymbolTool, codingGetCallHierarchyTool, codingGetDiagnosticsTool, codingGetExportsTool, codingGetImportsTool, codingGetOutlineTool, codingGetSymbolsTool, codingGoToDefinitionTool, codingMultiFileEditTool, codingRefactorRenameTool, codingToolsProject, countTokens, createContextWindowStateManager, createMcpToolProject, createMode, createSkillTools, createSummarizationReport, createSummarySystemMessage, createToolProject, dbCountTool, dbDeleteTool, dbInsertTool, dbQueryTool, dbSchemaTool, dbTablesTool, dbToolsProject, dbUpdateTool, diffApplyTool, diffCreateTool, diffPreviewTool, diffToolsProject, disconnectMcpToolProject, ensureGlobalConfigDir, ensureLocalConfigDir, estimateSummaryTokens, estimateTokenCount, execKillTool, execListProcessesTool, execReadOutputTool, execRunBackgroundTool, execRunBlockingTool, execRunShellTool, execRunTool, execTailOutputTool, execToolsProject, extractConversationKeypoints, fetchUrlAsBase64, fsAppendFileTool, fsBatchReadTool, fsBatchWriteTool, fsCopyTool, fsCreateDirTool, fsDeleteDirTool, fsDeleteFileTool, fsExistsTool, fsGlobTool, fsListDirTool, fsMoveTool, fsReadFileRangeTool, fsReadFileTool, fsReplaceInFileTool, fsSearchTool, fsStatTool, fsToolsProject, fsTreeTool, fsWriteFileTool, generateSummarizationPrompt, generateToolCategoriesPrompt, getContextWindowPercentage, getDefaultSlmModel, getGlobalConfigDir, getGlobalConfigPath, getGlobalToolpackDir, getLocalConfigDir, getLocalConfigPath, getLocalToolpackDir, getMessageStats, getMimeType, getOllamaBaseUrl, getOllamaProviderEntries, getRegisteredSlmModels, getRuntimeConfigStatus, getSafeOutputReserve, getToolSearchSchema, getToolpackConfig, getUserHomeDir, gitAddTool, gitBlameTool, gitBranchCreateTool, gitBranchListTool, gitCheckoutTool, gitCloneTool, gitCommitTool, gitDiffTool, gitLogTool, gitStatusTool, gitToolsProject, githubContentsGetTextTool, githubGraphqlExecuteTool, githubIssuesCommentsCreateTool, githubPrDiffGetTool, githubPrFilesListTool, githubPrReviewCommentsReplyTool, githubPrReviewThreadsListTool, githubPrReviewThreadsResolveTool, githubPrReviewsSubmitTool, githubToolsProject, groupMessagesByRole, handleContextWindowError, httpDeleteTool, httpDownloadTool, httpGetTool, httpPostTool, httpPutTool, httpToolsProject, initializeGlobalConfigIfFirstRun, isContextWindowError, isDataUri, isRegisteredSlm, isToolSearchTool, k8sApplyManifestTool, k8sDeleteResourceTool, k8sDescribeTool, k8sGetConfigMapTool, k8sGetLogsTool, k8sGetNamespacesTool, k8sListDeploymentsTool, k8sListPodsTool, k8sListServicesTool, k8sSwitchContextTool, k8sToolsProject, k8sWaitForDeploymentTool, loadFullConfig, loadRuntimeConfig, loadToolsConfig, mergeSummarizationResults, normalizeImagePart, ollamaRequest, ollamaStream, parseDataUri, parseSkillFile, parseSummarizationResponse, prepareSummarizationRequest, pruneMessages, readFileAsBase64, reloadToolpackConfig, removeBypassRule, saveToolsConfig, slackAuthTestTool, slackChatPostEphemeralTool, slackChatPostMessageTool, slackConversationsHistoryTool, slackConversationsRepliesTool, slackReactionsAddTool, slackToolsProject, systemCwdTool, systemDiskUsageTool, systemEnvTool, systemInfoTool, systemSetEnvTool, systemToolsProject, toDataUri, toolSearchDefinition, truncateMessage, validateSummarizationResult, webExtractLinksTool, webFeedTool, webFetchTool, webMapTool, webMetadataTool, webScrapeTool, webScreenshotTool, webSearchTool, webSitemapTool, webToolsProject, wouldExceedContextWindow };
+export { AGENT_MODE, AGENT_PLANNING_PROMPT, AGENT_WORKFLOW, AIClient, type AIClientConfig, type AddBypassRuleOptions, AnthropicAdapter, AnthropicVertexAdapter, type AnthropicVertexConfig, type AssembledPrompt, type AssemblerOptions, AuthenticationError, BM25Engine, BM25SearchEngine, type BM25SearchResult, BUILT_IN_MODES, type BypassRuleType, CHAT_MODE, CHAT_WORKFLOW, CODING_MODE, CODING_PLANNING_PROMPT, CODING_WORKFLOW, CONFIG_DIR_NAME, CONFIG_FILE_NAME, type CompletionChunk, type CompletionOptions, type CompletionRequest, type CompletionResponse, type ConfirmationDecision, type ConfirmationLevel$1 as ConfirmationLevel, ConnectionError, type ContextPrunedEvent, type ContextWindowConfig, ContextWindowConfigError, ContextWindowExceededError, type ContextWindowExceededEvent, type ContextWindowState, ContextWindowStateManager, type ContextWindowStrategy, type ContextWindowWarningEvent, ConversationNotFoundError, type ConversationScope, type ConversationSearchOptions, type ConversationStore, type ConversationSummarizedEvent, DEFAULT_MODE_NAME, DEFAULT_TOOLS_CONFIG, DEFAULT_TOOL_SEARCH_CONFIG, DEFAULT_WORKFLOW, DEFAULT_WORKFLOW_CONFIG, type EmbeddingRequest, type EmbeddingResponse, FILE_LIMITS, type FileEnvelope, type FilePart, type FileUploadRequest, type FileUploadResponse, GeminiAdapter, type GetOptions, type HitlConfig, type ImageDataPart, type ImageFilePart, type ImagePart, type ImageUrlPart, InMemoryConversationStore, type InMemoryConversationStoreConfig, InsufficientContextError, InvalidRequestError, type JsonRpcRequest, type JsonRpcResponse, type KnowledgeInstance, type McpAgentDefinition, type McpAuthConfig, McpClient, type McpClientConfig, McpConnectionError, type McpCustomAuthConfig, type McpJwtAuthConfig, type McpServerCapabilities, type McpServerConfig, type McpServerExposeConfig, type McpServerHandle, type McpStaticAuthConfig, McpTimeoutError, type McpTool, McpToolManager, type McpToolsConfig, type McpTransport, type MediaOptions, type MediaUploadStrategy, type Message, type MessageContent, type ModeBlockedHint, type ModeConfig, ModeRegistry, OllamaAdapter, type OllamaAdapterConfig, type OllamaModelInfo, OllamaProvider, type OllamaProviderEntry, type OnToolConfirmCallback, OpenAIAdapter, OpenRouterAdapter, type OpenRouterOptions, PageError, type Participant, type Plan, type PlanStep, Planner, type PromptMessage, ProviderAdapter, type ProviderConfig, ProviderError, type ProviderInfo, type ProviderModelInfo, type ProviderOptions, type PruneResult, RateLimitError, type RequestToolDefinition, type Role, RuleLoader, type RuntimeConfigStatus, SDKError, SQLiteConversationStore, type SQLiteConversationStoreConfig, type SearchHistoryEntry, type SearchOptions, type SearchResult, type Skill, type SkillSection, type SkillToolsOptions, type SkillValidationMode, type SlmModelEntry, type StoredMessage, SummarizationError, type SummarizationOptions, type SummarizationResult, TOOLPACK_DIR_NAME, TOOL_SEARCH_NAME, type TextPart, TimeoutError, type ToolActor, type ToolAnnotations, type ToolCall, type ToolCallFunction, type ToolCallMessage, type ToolCallRequest, type ToolCallResult, type ToolCategory, type ToolConfirmation, type ToolConfirmationRequestedEvent, type ToolConfirmationResolvedEvent, type ToolContext, type ToolDefinition, ToolDiscoveryCache, type ToolLogEvent, type ToolParameterProperty, type ToolParameters, type ToolProgressEvent, type ToolProject, type ToolProjectDependencies, type ToolProjectManifest, ToolRegistry, type ToolResult, ToolRouter, type ToolSchema, type ToolSearchConfig, Toolpack, type ToolpackConfig, type ToolpackCredentials, type ToolpackInitConfig, type ToolpackInterceptor, type ToolpackMcpServerConfig, type ToolpackNextFunction, type ToolsConfig, type Usage, VertexAIAdapter, type VertexAIConfig, type WorkflowConfig, type WorkflowEvents, WorkflowExecutor, type WorkflowProgress, type WorkflowResult, addBypassRule, buildSummarizedHistory, cloudDeployTool, cloudListTool, cloudStatusTool, cloudToolsProject, codingExtractFunctionTool, codingFindReferencesTool, codingFindSymbolTool, codingGetCallHierarchyTool, codingGetDiagnosticsTool, codingGetExportsTool, codingGetImportsTool, codingGetOutlineTool, codingGetSymbolsTool, codingGoToDefinitionTool, codingMultiFileEditTool, codingRefactorRenameTool, codingToolsProject, countTokens, createContextWindowStateManager, createMcpToolProject, createMode, createSkillTools, createSummarizationReport, createSummarySystemMessage, createToolProject, dbCountTool, dbDeleteTool, dbInsertTool, dbQueryTool, dbSchemaTool, dbTablesTool, dbToolsProject, dbUpdateTool, diffApplyTool, diffCreateTool, diffPreviewTool, diffToolsProject, disconnectMcpToolProject, ensureGlobalConfigDir, ensureLocalConfigDir, estimateSummaryTokens, estimateTokenCount, execKillTool, execListProcessesTool, execReadOutputTool, execRunBackgroundTool, execRunBlockingTool, execRunShellTool, execRunTool, execTailOutputTool, execToolsProject, extractConversationKeypoints, fetchUrlAsBase64, fsAppendFileTool, fsBatchReadTool, fsBatchWriteTool, fsCopyTool, fsCreateDirTool, fsDeleteDirTool, fsDeleteFileTool, fsExistsTool, fsGlobTool, fsListDirTool, fsMoveTool, fsReadFileRangeTool, fsReadFileTool, fsReplaceInFileTool, fsSearchTool, fsStatTool, fsToolsProject, fsTreeTool, fsWriteFileTool, generateSummarizationPrompt, generateToolCategoriesPrompt, getContextWindowPercentage, getDefaultSlmModel, getGlobalConfigDir, getGlobalConfigPath, getGlobalToolpackDir, getLocalConfigDir, getLocalConfigPath, getLocalToolpackDir, getMessageStats, getMimeType, getOllamaBaseUrl, getOllamaProviderEntries, getRegisteredSlmModels, getRuntimeConfigStatus, getSafeOutputReserve, getToolSearchSchema, getToolpackConfig, getUserHomeDir, gitAddTool, gitBlameTool, gitBranchCreateTool, gitBranchListTool, gitCheckoutTool, gitCloneTool, gitCommitTool, gitDiffTool, gitLogTool, gitStatusTool, gitToolsProject, githubContentsGetTextTool, githubGraphqlExecuteTool, githubIssuesCommentsCreateTool, githubPrDiffGetTool, githubPrFilesListTool, githubPrReviewCommentsReplyTool, githubPrReviewThreadsListTool, githubPrReviewThreadsResolveTool, githubPrReviewsSubmitTool, githubToolsProject, groupMessagesByRole, handleContextWindowError, httpDeleteTool, httpDownloadTool, httpGetTool, httpPostTool, httpPutTool, httpToolsProject, initializeGlobalConfigIfFirstRun, isContextWindowError, isDataUri, isRegisteredSlm, isToolSearchTool, k8sApplyManifestTool, k8sDeleteResourceTool, k8sDescribeTool, k8sGetConfigMapTool, k8sGetLogsTool, k8sGetNamespacesTool, k8sListDeploymentsTool, k8sListPodsTool, k8sListServicesTool, k8sSwitchContextTool, k8sToolsProject, k8sWaitForDeploymentTool, loadFullConfig, loadRuntimeConfig, loadToolsConfig, mergeSummarizationResults, normalizeImagePart, ollamaRequest, ollamaStream, parseDataUri, parseFileEnvelope, parseSkillFile, parseSummarizationResponse, prepareSummarizationRequest, pruneMessages, readFileAsBase64, reloadToolpackConfig, removeBypassRule, saveToolsConfig, slackAuthTestTool, slackChatPostEphemeralTool, slackChatPostMessageTool, slackConversationsHistoryTool, slackConversationsRepliesTool, slackReactionsAddTool, slackToolsProject, systemCwdTool, systemDiskUsageTool, systemEnvTool, systemInfoTool, systemSetEnvTool, systemToolsProject, toDataUri, toolSearchDefinition, truncateMessage, validateSummarizationResult, webExtractLinksTool, webFeedTool, webFetchTool, webMapTool, webMetadataTool, webScrapeTool, webScreenshotTool, webSearchTool, webSitemapTool, webToolsProject, wouldExceedContextWindow };