Tools & Function Calling

constructor

constructor(
    private readonly agent: Agent,
    private readonly packageValue: SerializedAgentPackage,
  )

Parameters:

• agent: Agent
• packageValue: SerializedAgentPackage

start()

async start(): Promise<void>

Returns: Promise<void>

execute()

async execute(input: unknown): Promise<RemoteToolExecutionResponse>

Parameters:

• input: unknown

Returns: Promise<RemoteToolExecutionResponse>

close()

close(status: 'completed' | 'failed' | 'cancelled' = 'completed'): Promise<void>

Parameters:

• status: "completed" | "failed" | "cancelled" (optional) (default: 'completed')

Returns: Promise<void>

static enhanced()

Additive fixed audited contracts. Ordinary for()/factories/defaults are unchanged.

static enhanced(connectorOrName: Connector | string, options: EnhancedConnectorOptions): ToolFunction[]

Parameters:

• connectorOrName: string | Connector
• options: EnhancedConnectorOptions

Returns: ToolFunction<any, any>[]

static clearCache()

Clear all caches (useful for testing or when connectors change)

static clearCache(): void

Returns: void

static invalidateCache()

Invalidate cache for a specific connector

static invalidateCache(connectorName: string): void

Parameters:

• connectorName: string

Returns: void

static registerService()

Register a tool factory for a service type

static registerService(serviceType: string, factory: ServiceToolFactory): void

Parameters:

• serviceType: string
• factory: ServiceToolFactory

Returns: void

static unregisterService()

Unregister a service tool factory

static unregisterService(serviceType: string): boolean

Parameters:

• serviceType: string

Returns: boolean

static for()

Get ALL tools for a connector (generic API + service-specific) This is the main entry point

static for(connectorOrName: Connector | string, userId?: string, options?: ConnectorToolsOptions): ToolFunction[]

Parameters:

• connectorOrName: string | Connector
• userId: string | undefined (optional)
• options: ConnectorToolsOptions | undefined (optional)

Returns: ToolFunction<any, any>[]

static discoverAll()

Discover tools for ALL registered connectors with external services Skips AI provider connectors (those with vendor but no serviceType)

static discoverAll(userId?: string, options?: ConnectorToolsOptions): Map<string, ToolFunction[]>

Parameters:

• userId: string | undefined (optional)
• options: ConnectorToolsOptions | undefined (optional)

Returns: Map<string, ToolFunction<any, any>[]>

static findConnector()

Find a connector by service type Returns the first connector matching the service type

static findConnector(serviceType: string, options?: ConnectorToolsOptions): Connector | undefined

Parameters:

• serviceType: string
• options: ConnectorToolsOptions | undefined (optional)

Returns: Connector | undefined

static findConnectors()

Find all connectors for a service type Useful when you have multiple connectors for the same service

static findConnectors(serviceType: string, options?: ConnectorToolsOptions): Connector[]

Parameters:

• serviceType: string
• options: ConnectorToolsOptions | undefined (optional)

Returns: Connector[]

static listSupportedServices()

List services that have registered tool factories

static listSupportedServices(): string[]

Returns: string[]

static hasServiceTools()

Check if a service has dedicated tool factory

static hasServiceTools(serviceType: string): boolean

Parameters:

• serviceType: string

Returns: boolean

static detectService()

Detect the service type for a connector Uses explicit serviceType if set, otherwise infers from baseURL Results are cached for performance

static detectService(connector: Connector): string | undefined

Parameters:

• connector: Connector

Returns: string | undefined

static forIdentities()

Generate tools for a set of auth identities. Each identity gets its own tool set with unique name prefixes.

static forIdentities(
    identities: AuthIdentity[],
    userId?: string,
    options?: { registry?: IConnectorRegistry }
  ): Map<string, ToolFunction[]>

Parameters:

• identities: AuthIdentity[]
• userId: string | undefined (optional)
• options: { registry?: IConnectorRegistry | undefined; } | undefined (optional)

Returns: Map<string, ToolFunction<any, any>[]>

constructor

constructor(
    toolName: string,
    public readonly rawArguments: string,
    public readonly parseError?: Error
  )

Parameters:

• toolName: string
• rawArguments: string
• parseError: Error | undefined (optional)

constructor

constructor(
    message: string,
    public readonly toolName: string,
    serverName?: string,
    cause?: Error
  )

Parameters:

• message: string
• toolName: string
• serverName: string | undefined (optional)
• cause: Error | undefined (optional)

constructor

constructor(code: string, message: string, retryable = false)

Parameters:

• code: string
• message: string
• retryable: boolean (optional) (default: false)

constructor

constructor(private readonly promptView?: (handler: IStoreHandler) =>
    Pick<StoreEntrySchema, 'description' | 'usageHint'> | undefined)

Parameters:

• promptView: ((handler: IStoreHandler) => Pick<StoreEntrySchema, "description" | "usageHint"> | undefined) | undefined (optional)

registerHandler()

Register a store handler. Throws on duplicate storeId.

registerHandler(handler: IStoreHandler): void

Parameters:

• handler: IStoreHandler

Returns: void

unregisterHandler()

Unregister a store handler by storeId.

unregisterHandler(storeId: string): boolean

Parameters:

• storeId: string

Returns: boolean

getHandler()

Get a handler by storeId.

getHandler(storeId: string): IStoreHandler | undefined

Parameters:

• storeId: string

Returns: IStoreHandler | undefined

getSchemas()

Get all registered store schemas (for building tool descriptions).

getSchemas(): StoreEntrySchema[]

Returns: StoreEntrySchema[]

getStoreIds()

Get all registered store IDs.

getStoreIds(): string[]

Returns: string[]

getTools()

Create the 5 generic store tools. Called once when the first IStoreHandler is registered.

getTools(): ToolFunction[]

Returns: ToolFunction<any, any>[]

destroy()

Cleanup.

destroy(): void

Returns: void

buildOverview()

Build the unified overview block for system instructions. Emitted once when any IStoreHandler plugins are registered. Covers: what store_* tools are, available stores, and when to use each.

buildOverview(): string

Returns: string

constructor

constructor(config?: ToolCatalogPluginConfig)

Parameters:

• config: ToolCatalogPluginConfig | undefined (optional)

getInstructions()

getInstructions(): string

Returns: string

getInstructionsTokenSize()

getInstructionsTokenSize(): number

Returns: number

getContent()

async getContent(): Promise<string | null>

Returns: Promise<string | null>

getContents()

getContents(): unknown

Returns: unknown

getTools()

getTools(): ToolFunction[]

Returns: ToolFunction<any, any>[]

isCompactable()

isCompactable(): boolean

Returns: boolean

compact()

async compact(targetTokensToFree: number): Promise<number>

Parameters:

• targetTokensToFree: number

Returns: Promise<number>

getState()

getState(): unknown

Returns: unknown

restoreState()

restoreState(state: unknown): void

Parameters:

• state: unknown

Returns: void

destroy()

destroy(): void

Returns: void

setToolManager()

Set the ToolManager reference. Called by AgentContextNextGen after plugin registration.

setToolManager(tm: ToolManager): void

Parameters:

• tm: ToolManager

Returns: void

executeLoad()

executeLoad(category: string): Record<string, unknown>

Parameters:

• category: string

Returns: Record<string, unknown>

static toDisplayName()

Convert a hyphenated or plain name to a display name. E.g., 'custom-tools' → 'Custom Tools', 'filesystem' → 'Filesystem'

static toDisplayName(name: string): string

Parameters:

• name: string

Returns: string

static parseConnectorCategory()

Parse a connector category name into connector name + optional accountId.

Formats:

• 'connector:github' → { connectorName: 'github' }
• 'connector:microsoft:work' → { connectorName: 'microsoft', accountId: 'work' }
• 'filesystem' → null (not a connector category)

static parseConnectorCategory(category: string): ParsedConnectorCategory | null

Parameters:

• category: string

Returns: ParsedConnectorCategory | null

static getConnectorToolsModule()

Get the ConnectorTools module (lazy-loaded, cached). Returns null if ConnectorTools is not available. Uses false sentinel to prevent retrying after first failure.

NOTE: The dynamic require() path fails in bundled environments (Meteor, Webpack). Call setConnectorToolsModule() at app startup to inject the module explicitly.

static getConnectorToolsModule(): { ConnectorTools: any } | null

Returns: { ConnectorTools: any; } | null

static setConnectorToolsModule()

Explicitly set the ConnectorTools module reference.

Use this in bundled environments (Meteor, Webpack, etc.) where the lazy require('../../tools/connector/ConnectorTools.js') fails due to path resolution.

static setConnectorToolsModule(mod: { ConnectorTools: any }): void

Parameters:

• mod: { ConnectorTools: any; }

Returns: void

static registerCategory()

Register a tool category. If the category already exists, updates its metadata.

static registerCategory(def: ToolCategoryDefinition): void

Parameters:

• def: ToolCategoryDefinition

Returns: void

static registerTools()

Register multiple tools in a category. The category is auto-created if it doesn't exist (with a generic description).

static registerTools(category: string, tools: CatalogToolEntry[]): void

Parameters:

• category: string
• tools: CatalogToolEntry[]

Returns: void

static registerTool()

Register a single tool in a category.

static registerTool(category: string, tool: CatalogToolEntry): void

Parameters:

• category: string
• tool: CatalogToolEntry

Returns: void

static unregisterCategory()

Unregister a category and all its tools.

static unregisterCategory(category: string): boolean

Parameters:

• category: string

Returns: boolean

static unregisterTool()

Unregister a single tool from a category.

static unregisterTool(category: string, toolName: string): boolean

Parameters:

• category: string
• toolName: string

Returns: boolean

static getCategories()

Get all registered categories.

static getCategories(): ToolCategoryDefinition[]

Returns: ToolCategoryDefinition[]

static getCategory()

Get a single category by name.

static getCategory(name: string): ToolCategoryDefinition | undefined

Parameters:

• name: string

Returns: ToolCategoryDefinition | undefined

static hasCategory()

Check if a category exists.

static hasCategory(name: string): boolean

Parameters:

• name: string

Returns: boolean

static getToolsInCategory()

Get all tools in a category.

static getToolsInCategory(category: string): CatalogToolEntry[]

Parameters:

• category: string

Returns: CatalogToolEntry[]

static getAllCatalogTools()

Get all catalog tools across all categories.

static getAllCatalogTools(): CatalogToolEntry[]

Returns: CatalogToolEntry[]

static findTool()

Find a tool by name across all categories.

static findTool(name: string): { category: string; entry: CatalogToolEntry } | undefined

Parameters:

• name: string

Returns: { category: string; entry: CatalogToolEntry; } | undefined

static filterCategories()

Filter categories by scope.

static filterCategories(scope?: ToolCategoryScope): ToolCategoryDefinition[]

Parameters:

• scope: ToolCategoryScope | undefined (optional)

Returns: ToolCategoryDefinition[]

static isCategoryAllowed()

Check if a category is allowed by a scope.

static isCategoryAllowed(name: string, scope?: ToolCategoryScope): boolean

Parameters:

• name: string
• scope: ToolCategoryScope | undefined (optional)

Returns: boolean

static discoverConnectorCategories()

Discover all connector categories with their tools.

When identities include accountId, uses ConnectorTools.forIdentities() to generate per-account categories (e.g., 'connector:microsoft:work', 'connector:microsoft:personal'). Without accountIds, falls back to ConnectorTools.discoverAll() for backward compatibility.

static discoverConnectorCategories(options?: {
    scope?: ToolCategoryScope;
    identities?: Array<{ connector: string; accountId?: string }>;
  }): ConnectorCategoryInfo[]

Parameters:

• options: { scope?: ToolCategoryScope | undefined; identities?: { connector: string; accountId?: string | undefined; }[] | undefined; } | undefined (optional)

Returns: ConnectorCategoryInfo[]

static resolveConnectorCategoryTools()

Resolve tools for a specific connector category.

Supports both legacy format ('connector:github') and multi-account format ('connector:microsoft:work'). When accountId is present, generates account-prefixed tools via ConnectorTools.for(connectorName, { accountId }).

static resolveConnectorCategoryTools(category: string): Array<{ tool: ToolFunction; name: string }>

Parameters:

• category: string

Returns: { tool: ToolFunction<any, any>; name: string; }[]

static resolveTools()

Resolve tool names to ToolFunction[].

Searches registered categories and (optionally) connector tools. Used by app-level executors (e.g., V25's OneRingAgentExecutor).

static resolveTools(
    toolNames: string[],
    options?: { includeConnectors?: boolean; userId?: string; context?: Record<string, unknown> },
  ): ToolFunction[]

Parameters:

• toolNames: string[]
• options: { includeConnectors?: boolean | undefined; userId?: string | undefined; context?: Record<string, unknown> | undefined; } | undefined (optional)

Returns: ToolFunction<any, any>[]

static resolveToolsGrouped()

Resolve tools grouped by connector name.

Tools with a connectorName go into byConnector; all others go into plain. Supports factory-based tool creation via createTool when context is provided.

static resolveToolsGrouped(
    toolNames: string[],
    context?: Record<string, unknown>,
    options?: { includeConnectors?: boolean },
  ): { plain: ToolFunction[]; byConnector: Map<string, ToolFunction[]> }

Parameters:

• toolNames: string[]
• context: Record<string, unknown> | undefined (optional)
• options: { includeConnectors?: boolean | undefined; } | undefined (optional)

Returns: { plain: ToolFunction<any, any>[]; byConnector: Map<string, ToolFunction<any, any>[]>; }

static ensureInitialized()

Ensure built-in tools from registry.generated.ts are registered. Called lazily on first query.

In ESM environments, call initializeFromRegistry(toolRegistry) explicitly from your app startup instead of relying on auto-initialization.

static ensureInitialized(): void

Returns: void

static initializeFromRegistry()

Explicitly initialize from the generated tool registry. Call this at app startup in ESM environments where lazy require() doesn't work.

static initializeFromRegistry(registry: ToolRegistryEntry[]): void

Parameters:

• registry: ToolRegistryEntry[]

Returns: void

static reset()

Reset the registry. Primarily for testing.

static reset(): void

Returns: void

constructor

constructor(config: ToolEvidenceConfig)

Parameters:

• config: ToolEvidenceConfig

record()

async record(tool: ToolFunction, args: unknown, context: ToolContext, outcome: ToolExecutionOutcome,
    result?: { value: unknown }, late = false, observeWork?: (promise: Promise<unknown>) => void): Promise<ToolEvidenceDelivery>

Parameters:

• tool: ToolFunction<any, any>
• args: unknown
• context: ToolContext
• outcome: ToolExecutionOutcome
• result: { value: unknown; } | undefined (optional)
• late: boolean (optional) (default: false)
• observeWork: ((promise: Promise<unknown>) => void) | undefined (optional)

Returns: Promise<ToolEvidenceDelivery>

constructor

constructor(
    toolName: string,
    message: string,
    public readonly originalError?: Error
  )

Parameters:

• toolName: string
• message: string
• originalError: Error | undefined (optional)

constructor

constructor(options: ToolExecutionPipelineOptions = {})

Parameters:

• options: ToolExecutionPipelineOptions (optional) (default: {})

use()

Register a plugin with the pipeline.

If a plugin with the same name is already registered, it will be unregistered first (calling its onUnregister hook) and replaced.

use(plugin: IToolExecutionPlugin): this

Parameters:

• plugin: IToolExecutionPlugin

Returns: this

remove()

Remove a plugin by name.

remove(pluginName: string): boolean

Parameters:

• pluginName: string

Returns: boolean

has()

Check if a plugin is registered.

has(pluginName: string): boolean

Parameters:

• pluginName: string

Returns: boolean

get()

Get a registered plugin by name.

get(pluginName: string): IToolExecutionPlugin | undefined

Parameters:

• pluginName: string

Returns: IToolExecutionPlugin | undefined

list()

List all registered plugins, sorted by priority.

list(): IToolExecutionPlugin[]

Returns: IToolExecutionPlugin[]

execute()

Execute a tool through the plugin pipeline.

Execution phases:

1. beforeExecute hooks (in priority order, lowest first)
2. Tool execution (if not aborted)
3. afterExecute hooks (in reverse priority order for proper unwinding)
4. onError hooks if any phase fails

async execute(tool: ToolFunction, args: unknown, options: PipelineExecutionOptions = {}): Promise<unknown>

Parameters:

• tool: ToolFunction<any, any>
• args: unknown
• options: PipelineExecutionOptions (optional) (default: {})

Returns: Promise<unknown>

constructor

constructor(config?: ToolManagerConfig)

Parameters:

• config: ToolManagerConfig | undefined (optional)

destroy()

Releases all resources held by this ToolManager. Cleans up circuit breaker listeners and removes all event listeners. Safe to call multiple times (idempotent).

destroy(): void

Returns: void

setToolContext()

Set tool context for execution (called by agent before runs). WARNING: This REPLACES the entire context. Prefer mergeToolContext() for partial updates.

setToolContext(context: ToolContext | undefined): void

Parameters:

• context: ToolContext | undefined

Returns: void

mergeToolContext()

Merge partial updates into the existing tool context. Unlike setToolContext(), this preserves fields not present in the partial update. Use this when updating userId or connectorAccounts without wiping agentId, identities, etc.

mergeToolContext(partial: Partial<ToolContext>): void

Parameters:

• partial: Partial<ToolContext>

Returns: void

getToolContext()

Get current tool context

getToolContext(): ToolContext | undefined

Returns: ToolContext | undefined

setPermissionManager()

Set permission policy manager for tool execution enforcement.

Registers a PermissionEnforcementPlugin on the execution pipeline at priority 1. This gates ALL tool execution through the policy chain — no bypasses.

setPermissionManager(manager: PermissionPolicyManager): void

Parameters:

• manager: PermissionPolicyManager

Returns: void

getPermissionManager()

Get the permission policy manager (if enforcement is active).

getPermissionManager(): PermissionPolicyManager | undefined

Returns: PermissionPolicyManager | undefined

hasPermissionEnforcement()

Check if permission enforcement is active on the execution pipeline.

hasPermissionEnforcement(): boolean

Returns: boolean

register()

Register a tool with optional configuration

register(tool: ToolFunction, options: ToolOptions = {}): void

Parameters:

• tool: ToolFunction<any, any>
• options: ToolOptions (optional) (default: {})

Returns: void

registerMany()

Register multiple tools at once

registerMany(tools: ToolFunction[], options: Omit<ToolOptions, 'conditions'> = {}): void

Parameters:

• tools: ToolFunction<any, any>[]
• options: Omit<ToolOptions, "conditions"> (optional) (default: {})

Returns: void

registerConnectorTools()

Register tools produced by a specific connector. Sets source: 'connector:<connectorName>' (or 'connector:<name>:<accountId>' for identity-bound tools) so agent-level filtering can restrict which connector tools are visible to a given agent.

registerConnectorTools(connectorName: string, tools: ToolFunction[], options: Omit<ToolOptions, 'source'> & { accountId?: string } = {}): void

Parameters:

• connectorName: string
• tools: ToolFunction<any, any>[]
• options: Omit<ToolOptions, "source"> & { accountId?: string | undefined; } (optional) (default: {})

Returns: void

unregister()

Unregister a tool by name

unregister(name: string): boolean

Parameters:

• name: string

Returns: boolean

clear()

Clear all tools and their circuit breakers. Does NOT remove event listeners from this ToolManager (use destroy() for full cleanup).

clear(): void

Returns: void

enable()

Enable a tool by name

enable(name: string): boolean

Parameters:

• name: string

Returns: boolean

disable()

Disable a tool by name (keeps it registered but inactive)

disable(name: string): boolean

Parameters:

• name: string

Returns: boolean

toggle()

Toggle a tool's enabled state

toggle(name: string): boolean

Parameters:

• name: string

Returns: boolean

isEnabled()

Check if a tool is enabled

isEnabled(name: string): boolean

Parameters:

• name: string

Returns: boolean

setEnabled()

Set enabled state for multiple tools

setEnabled(names: string[], enabled: boolean): void

Parameters:

• names: string[]
• enabled: boolean

Returns: void

setNamespace()

Set the namespace for a tool

setNamespace(toolName: string, namespace: string): boolean

Parameters:

• toolName: string
• namespace: string

Returns: boolean

enableNamespace()

Enable all tools in a namespace

enableNamespace(namespace: string): void

Parameters:

• namespace: string

Returns: void

disableNamespace()

Disable all tools in a namespace

disableNamespace(namespace: string): void

Parameters:

• namespace: string

Returns: void

getNamespaces()

Get all namespace names

getNamespaces(): string[]

Returns: string[]

createNamespace()

Create a namespace with tools

createNamespace(namespace: string, tools: ToolFunction[], options: Omit<ToolOptions, 'namespace'> = {}): void

Parameters:

• namespace: string
• tools: ToolFunction<any, any>[]
• options: Omit<ToolOptions, "namespace"> (optional) (default: {})

Returns: void

setPriority()

Set priority for a tool

setPriority(name: string, priority: number): boolean

Parameters:

• name: string
• priority: number

Returns: boolean

getPriority()

Get priority for a tool

getPriority(name: string): number | undefined

Parameters:

• name: string

Returns: number | undefined

getPermission()

Get permission config for a tool

getPermission(name: string): ToolPermissionConfig | undefined

Parameters:

• name: string

Returns: ToolPermissionConfig | undefined

setPermission()

Set permission config for a tool

setPermission(name: string, permission: ToolPermissionConfig): boolean

Parameters:

• name: string
• permission: ToolPermissionConfig

Returns: boolean

get()

Get a tool by name

get(name: string): ToolFunction | undefined

Parameters:

• name: string

Returns: ToolFunction<any, any> | undefined

has()

Check if a tool exists

has(name: string): boolean

Parameters:

• name: string

Returns: boolean

getEnabled()

Get all enabled tools (sorted by priority)

getEnabled(): ToolFunction[]

Returns: ToolFunction<any, any>[]

getEnabledRegistrations()

Get all enabled registrations (sorted by priority). Includes full registration metadata (source, namespace, etc.) for use in connector-aware filtering.

getEnabledRegistrations(): ToolRegistration[]

Returns: ToolRegistration[]

getAll()

Get all tools (enabled and disabled)

getAll(): ToolFunction[]

Returns: ToolFunction<any, any>[]

getByNamespace()

Get tools by namespace

getByNamespace(namespace: string): ToolFunction[]

Parameters:

• namespace: string

Returns: ToolFunction<any, any>[]

getByCategory()

Get all registered tool names in a category. Used by ToolCatalogPlugin for bulk enable/disable.

getByCategory(category: string): string[]

Parameters:

• category: string

Returns: string[]

getRegistration()

Get tool registration info

getRegistration(name: string): ToolRegistration | undefined

Parameters:

• name: string

Returns: ToolRegistration | undefined

list()

List all tool names

list(): string[]

Returns: string[]

listEnabled()

List enabled tool names

listEnabled(): string[]

Returns: string[]

listCompact()

Slim catalog of currently enabled tools — name + description, no parameter schemas.

Used by routine builders to discover what's available on a superagent without paying the token cost of full tool definitions. Each entry includes:

• name: the LLM-facing tool name (already connector-prefixed for connector tools, e.g. msft-personal_send_email)
• description: the tool's definition.function.description
• category: optional grouping
• connectorName: present for connector-bound tools (read from tool.connectorName, falling back to parsing the registration source like 'connector:msft-personal' or 'connector:msft-personal:account-id')

Disabled tools are excluded — they're not actually callable by the LLM, so listing them would mislead a routine builder.

listCompact(): CompactToolDescriptor[]

Returns: CompactToolDescriptor[]

selectForContext()

Select tools based on context (uses conditions and smart filtering)

selectForContext(context: ToolSelectionContext): ToolFunction[]

Parameters:

• context: ToolSelectionContext

Returns: ToolFunction<any, any>[]

selectByCapability()

Select tools by matching capability description

selectByCapability(description: string): ToolFunction[]

Parameters:

• description: string

Returns: ToolFunction<any, any>[]

selectWithinBudget()

Filter tools to fit within a token budget

selectWithinBudget(budget: number): ToolFunction[]

Parameters:

• budget: number

Returns: ToolFunction<any, any>[]

recordExecution()

Record tool execution (called by agent/loop)

recordExecution(
    name: string,
    executionMs: number,
    success: boolean
  ): void

Parameters:

• name: string
• executionMs: number
• success: boolean

Returns: void

getStats()

Get comprehensive statistics

getStats(): ToolManagerStats

Returns: ToolManagerStats

setEvidenceMiddleware()

Opt-in post-settlement evidence handling. Does not replace the execution pipeline.

setEvidenceMiddleware(middleware?: ToolEvidenceMiddleware): void

Parameters:

• middleware: ToolEvidenceMiddleware | undefined (optional)

Returns: void

execute()

Execute a tool function with circuit breaker protection and plugin pipeline. Implements IToolExecutor interface.

Execution flow:

1. Validate tool exists and is enabled
2. Check circuit breaker state
3. Run through plugin pipeline (beforeExecute -> execute -> afterExecute)
4. Update metrics and circuit breaker state

Simple execution - no caching, no parent context. Context must be set via setToolContext() before calling.

async execute(toolName: string, args: any, options?: ToolExecutionOptions): Promise<any>

Parameters:

• toolName: string
• args: any
• options: ToolExecutionOptions | undefined (optional)

Returns: Promise<any>

executeWithOutcome()

Execute with semantic metadata while retaining the legacy raw result contract.

async executeWithOutcome(toolName: string, args: any, options: ToolExecutionOptions = {}): Promise<ToolExecutionReport<any>>

Parameters:

• toolName: string
• args: any
• options: ToolExecutionOptions (optional) (default: {})

Returns: Promise<ToolExecutionReport<any>>

hasToolFunction()

Check if tool is available (IToolExecutor interface)

hasToolFunction(toolName: string): boolean

Parameters:

• toolName: string

Returns: boolean

getToolDefinition()

Get tool definition (IToolExecutor interface)

getToolDefinition(toolName: string): Tool | undefined

Parameters:

• toolName: string

Returns: Tool | undefined

registerTool()

Register a tool (IToolExecutor interface - delegates to register())

registerTool(tool: ToolFunction): void

Parameters:

• tool: ToolFunction<any, any>

Returns: void

unregisterTool()

Unregister a tool (IToolExecutor interface - delegates to unregister())

unregisterTool(toolName: string): void

Parameters:

• toolName: string

Returns: void

listTools()

List all registered tool names (IToolExecutor interface - delegates to list())

listTools(): string[]

Returns: string[]

getCircuitBreakerStates()

Get circuit breaker states for all tools

getCircuitBreakerStates(): Map<string, CircuitState>

Returns: Map<string, CircuitState>

getToolCircuitBreakerMetrics()

Get circuit breaker metrics for a specific tool

getToolCircuitBreakerMetrics(toolName: string)

Parameters:

• toolName: string

Returns: CircuitBreakerMetrics | undefined

resetToolCircuitBreaker()

Manually reset a tool's circuit breaker

resetToolCircuitBreaker(toolName: string): void

Parameters:

• toolName: string

Returns: void

setCircuitBreakerConfig()

Configure circuit breaker for a tool

setCircuitBreakerConfig(toolName: string, config: CircuitBreakerConfig): boolean

Parameters:

• toolName: string
• config: CircuitBreakerConfig

Returns: boolean

getState()

Get serializable state (for session persistence)

getState(): SerializedToolState

Returns: SerializedToolState

loadState()

Load state (restores enabled/disabled, namespaces, priorities, permissions) Note: Tools must be re-registered separately (they contain functions)

loadState(state: SerializedToolState): void

Parameters:

• state: SerializedToolState

Returns: void

constructor

constructor(toolName: string)

Parameters:

• toolName: string

constructor

constructor(config?: AgentPermissionsConfig)

Parameters:

• config: AgentPermissionsConfig | undefined (optional)

checkPermission()

Check if a tool needs approval before execution

checkPermission(toolName: string, _args?: Record<string, unknown>): PermissionCheckResult

Parameters:

• toolName: string
• _args: Record<string, unknown> | undefined (optional)

Returns: PermissionCheckResult

needsApproval()

Check if a tool call needs approval (uses ToolCall object)

needsApproval(toolCall: ToolCall): boolean

Parameters:

• toolCall: ToolCall

Returns: boolean

isBlocked()

Check if a tool is blocked

isBlocked(toolName: string): boolean

Parameters:

• toolName: string

Returns: boolean

isApproved()

Check if a tool is approved (either allowlisted or session-approved)

isApproved(toolName: string): boolean

Parameters:

• toolName: string

Returns: boolean

approve()

Approve a tool (record approval)

approve(toolName: string, decision?: Partial<ApprovalDecision>): void

Parameters:

• toolName: string
• decision: Partial<ApprovalDecision> | undefined (optional)

Returns: void

approveForSession()

Approve a tool for the entire session

approveForSession(toolName: string, approvedBy?: string): void

Parameters:

• toolName: string
• approvedBy: string | undefined (optional)

Returns: void

revoke()

Revoke a tool's approval

revoke(toolName: string): void

Parameters:

• toolName: string

Returns: void

deny()

Deny a tool execution (for audit trail)

deny(toolName: string, reason: string): void

Parameters:

• toolName: string
• reason: string

Returns: void

isApprovedForSession()

Check if a tool has been approved for the current session

isApprovedForSession(toolName: string): boolean

Parameters:

• toolName: string

Returns: boolean

allowlistAdd()

Add a tool to the allowlist (always allowed)

allowlistAdd(toolName: string): void

Parameters:

• toolName: string

Returns: void

allowlistRemove()

Remove a tool from the allowlist

allowlistRemove(toolName: string): void

Parameters:

• toolName: string

Returns: void

isAllowlisted()

Check if a tool is in the allowlist

isAllowlisted(toolName: string): boolean

Parameters:

• toolName: string

Returns: boolean

getAllowlist()

Get all allowlisted tools

getAllowlist(): string[]

Returns: string[]

blocklistAdd()

Add a tool to the blocklist (always blocked)

blocklistAdd(toolName: string): void

Parameters:

• toolName: string

Returns: void

blocklistRemove()

Remove a tool from the blocklist

blocklistRemove(toolName: string): void

Parameters:

• toolName: string

Returns: void

isBlocklisted()

Check if a tool is in the blocklist

isBlocklisted(toolName: string): boolean

Parameters:

• toolName: string

Returns: boolean

getBlocklist()

Get all blocklisted tools

getBlocklist(): string[]

Returns: string[]

setToolConfig()

Set permission config for a specific tool

setToolConfig(toolName: string, config: ToolPermissionConfig): void

Parameters:

• toolName: string
• config: ToolPermissionConfig

Returns: void

getToolConfig()

Get permission config for a specific tool

getToolConfig(toolName: string): ToolPermissionConfig | undefined

Parameters:

• toolName: string

Returns: ToolPermissionConfig | undefined

getEffectiveConfig()

Get effective config (tool-specific or defaults)

getEffectiveConfig(toolName: string): ToolPermissionConfig

Parameters:

• toolName: string

Returns: ToolPermissionConfig

requestApproval()

Request approval for a tool call

If an onApprovalRequired callback is set, it will be called. Otherwise, this auto-approves for backward compatibility.

NOTE: If you want to require explicit approval, you MUST either:

1. Set onApprovalRequired callback in AgentPermissionsConfig
2. Register an 'approve:tool' hook in the Agent
3. Add tools to the blocklist if they should never run

This auto-approval behavior preserves backward compatibility with existing code that doesn't use the permission system.

async requestApproval(context: PermissionCheckContext): Promise<ApprovalDecision>

Parameters:

• context: PermissionCheckContext

Returns: Promise<ApprovalDecision>

getApprovedTools()

Get all tools that have session approvals

getApprovedTools(): string[]

Returns: string[]

getApprovalEntry()

Get the approval entry for a tool

getApprovalEntry(toolName: string): ApprovalCacheEntry | undefined

Parameters:

• toolName: string

Returns: ApprovalCacheEntry | undefined

clearSession()

Clear all session approvals

clearSession(): void

Returns: void

getState()

Serialize approval state for persistence

getState(): SerializedApprovalState

Returns: SerializedApprovalState

loadState()

Load approval state from persistence

loadState(state: SerializedApprovalState): void

Parameters:

• state: SerializedApprovalState

Returns: void

getDefaults()

Get defaults

getDefaults(): { scope: PermissionScope; riskLevel: RiskLevel }

Returns: { scope: PermissionScope; riskLevel: RiskLevel; }

setDefaults()

Set defaults

setDefaults(defaults: { scope?: PermissionScope; riskLevel?: RiskLevel }): void

Parameters:

• defaults: { scope?: PermissionScope | undefined; riskLevel?: RiskLevel | undefined; }

Returns: void

getStats()

Get summary statistics

getStats(): {
    approvedCount: number;
    allowlistedCount: number;
    blocklistedCount: number;
    configuredCount: number;
  }

Returns: { approvedCount: number; allowlistedCount: number; blocklistedCount: number; configuredCount: number; }

reset()

Reset to initial state

reset(): void

Returns: void

destroy()

Destroy the permission manager and release all resources

destroy(): void

Returns: void

static getBuiltInTools()

Get built-in tools only (from registry.generated.ts)

static getBuiltInTools(): ToolRegistryEntry[]

Returns: ToolRegistryEntry[]

static getConnectorTools()

Get tools for a specific connector

static getConnectorTools(connectorName: string): ConnectorToolEntry[]

Parameters:

• connectorName: string

Returns: ConnectorToolEntry[]

static getAllConnectorTools()

Get all connector tools from all registered service connectors

This discovers tools from all connectors that have:

• Explicit serviceType, OR
• baseURL but no vendor (external API, not AI provider)

static getAllConnectorTools(): ConnectorToolEntry[]

Returns: ConnectorToolEntry[]

static getAllTools()

Get ALL tools (built-in + connector) - main API for UIs

This is the primary method for getting a complete list of available tools.

static getAllTools(): (ToolRegistryEntry | ConnectorToolEntry)[]

Returns: (ToolRegistryEntry | ConnectorToolEntry)[]

static getToolsByService()

Get tools filtered by service type

static getToolsByService(serviceType: string): ConnectorToolEntry[]

Parameters:

• serviceType: string

Returns: ConnectorToolEntry[]

static getToolsByConnector()

Get tools filtered by connector name

static getToolsByConnector(connectorName: string): ConnectorToolEntry[]

Parameters:

• connectorName: string

Returns: ConnectorToolEntry[]

static isConnectorTool()

Check if a tool entry is a connector tool

static isConnectorTool(entry: ToolRegistryEntry | ConnectorToolEntry): entry is ConnectorToolEntry

Parameters:

• entry: ToolRegistryEntry | ConnectorToolEntry

Returns: boolean

constructor

constructor(
    toolName: string,
    public readonly timeoutMs: number
  )

Parameters:

• toolName: string
• timeoutMs: number

onObservation()?

onObservation?(report: Readonly<RemoteOutcomeReport>): void;

Parameters:

• report: Readonly<RemoteOutcomeReport>

Returns: void

• When set: the per-tool targetUser schema parameter is OMITTED and this value is always used.
• When unset: existing behavior (LLM supplies targetUser for app-only auth).
• Silently ignored for delegated connectors (identity already bound by token).
• Empty / whitespace-only strings are treated as unset.

Use this when wiring a single shared app-token connector into a specific agent that should only ever operate on behalf of one user. The connector itself stays generic and can be reused with different actAs values across different agents.

SCOPE — only tools whose request URL is user-scoped participate in the lock. Tools that hit endpoints which are not user-scoped at the URL level (Microsoft /search/query; Google /drive/v3/files, /calendar/v3/freeBusy) do NOT take actAs and are unaffected by it — they always work with whatever the underlying token can see. Each non-participating tool's factory carries a NOTE on actAs lock doc block explaining the data-scope guarantee for that specific tool. If you need true per-user isolation for those tools, use a delegated connector (where the OAuth token binds identity directly). |

• 'tool_result' (default): the reply becomes the tool's actual output — semantically honest ("I asked → user answered → tool returned").
• 'user_message': reply is added as a fresh user turn — useful when you want the resumed turn to feel conversational. |

name: string;
description?: string;
parameters?: JSONSchema;
strict?: boolean; // Enforce schema strictly

};| - | |async?|async?: boolean;` | OpenAI Responses async tool calling. When true, a compatible model may continue its turn while the host executes this function. The eventual result must be returned with the original call ID.

This is a provider protocol flag and is distinct from blocking: false, which controls OneRingAI's managed agent execution loop. | | allowedCallers? | allowedCallers?: Array<'direct' | 'programmatic'>; | OpenAI tool invocation contexts. | | deferLoading? | deferLoading?: boolean; | Defer this tool for provider tool-search discovery. | | outputSchema? | outputSchema?: JSONSchema; | Schema for the JSON value encoded in the function output string. | | blocking? | blocking?: boolean; | - | | timeout? | timeout?: number; | - |

save()

Save a custom tool definition

save(userId: string | undefined, definition: CustomToolDefinition): Promise<void>;

Parameters:

• userId: string | undefined
• definition: CustomToolDefinition

Returns: Promise<void>

load()

Load a custom tool definition by name

load(userId: string | undefined, name: string): Promise<CustomToolDefinition | null>;

Parameters:

• userId: string | undefined
• name: string

Returns: Promise<CustomToolDefinition | null>

delete()

Delete a custom tool definition by name

delete(userId: string | undefined, name: string): Promise<void>;

Parameters:

• userId: string | undefined
• name: string

Returns: Promise<void>

exists()

Check if a custom tool exists

exists(userId: string | undefined, name: string): Promise<boolean>;

Parameters:

• userId: string | undefined
• name: string

Returns: Promise<boolean>

list()

List custom tools (summaries only)

list(userId: string | undefined, options?: CustomToolListOptions): Promise<CustomToolSummary[]>;

Parameters:

• userId: string | undefined
• options: CustomToolListOptions | undefined (optional)

Returns: Promise<CustomToolSummary[]>

updateMetadata()?

Update metadata without loading full definition

updateMetadata?(userId: string | undefined, name: string, metadata: Record<string, unknown>): Promise<void>;

Parameters:

• userId: string | undefined
• name: string
• metadata: Record<string, unknown>

Returns: Promise<void>

getPath()

Get the storage path/location for a specific user (for display/debugging)

getPath(userId: string | undefined): string;

Parameters:

• userId: string | undefined

Returns: string

use()

Register a plugin with the pipeline. If a plugin with the same name exists, it will be replaced.

use(plugin: IToolExecutionPlugin): this;

Parameters:

• plugin: IToolExecutionPlugin

Returns: this

remove()

Remove a plugin by name.

remove(pluginName: string): boolean;

Parameters:

• pluginName: string

Returns: boolean

has()

Check if a plugin is registered.

has(pluginName: string): boolean;

Parameters:

• pluginName: string

Returns: boolean

get()

Get a registered plugin by name.

get(pluginName: string): IToolExecutionPlugin | undefined;

Parameters:

• pluginName: string

Returns: IToolExecutionPlugin | undefined

list()

List all registered plugins (sorted by priority).

list(): IToolExecutionPlugin[];

Returns: IToolExecutionPlugin[]

execute()

Execute a tool through the plugin pipeline.

execute(tool: ToolFunction, args: unknown, options?: PipelineExecutionOptions): Promise<unknown>;

Parameters:

• tool: ToolFunction<any, any>
• args: unknown
• options: PipelineExecutionOptions | undefined (optional)

Returns: Promise<unknown>

beforeExecute()?

Called before tool execution.

Can:

• Return void to continue with original args
• Return { modifiedArgs } to continue with modified args
• Return { abort: true, result } to short-circuit and return immediately

beforeExecute?(ctx: PluginExecutionContext): Promise<BeforeExecuteResult>;

Parameters:

• ctx: PluginExecutionContext

Returns: Promise<BeforeExecuteResult>

afterExecute()?

Called after successful tool execution.

Can transform or replace the result. Must return the (possibly modified) result. Hooks run in reverse priority order for proper stack-like unwinding.

afterExecute?(ctx: PluginExecutionContext, result: unknown): Promise<unknown>;

Parameters:

• ctx: PluginExecutionContext
• result: unknown

Returns: Promise<unknown>

onError()?

Called when tool execution fails.

Can:

• Return undefined to let error propagate to next plugin/caller
• Return a value to recover from the error (returned as the result)
• Throw a different error

onError?(ctx: PluginExecutionContext, error: Error): Promise<unknown>;

Parameters:

• ctx: PluginExecutionContext
• error: Error

Returns: Promise<unknown>

onRegister()?

Called when plugin is registered with a pipeline. Use for setup that requires pipeline reference.

onRegister?(pipeline: IToolExecutionPipeline): void;

Parameters:

• pipeline: IToolExecutionPipeline

Returns: void

onUnregister()?

Called when plugin is unregistered from a pipeline. Use for cleanup.

onUnregister?(): void;

Returns: void

execute()

Execute a tool function

execute(toolName: string, args: any): Promise<any>;

Parameters:

• toolName: string
• args: any

Returns: Promise<any>

hasToolFunction()

Check if tool is available

hasToolFunction(toolName: string): boolean;

Parameters:

• toolName: string

Returns: boolean

getToolDefinition()

Get tool definition

getToolDefinition(toolName: string): Tool | undefined;

Parameters:

• toolName: string

Returns: Tool | undefined

registerTool()

Register a new tool

registerTool(tool: ToolFunction): void;

Parameters:

• tool: ToolFunction<any, any>

Returns: void

unregisterTool()

Unregister a tool

unregisterTool(toolName: string): void;

Parameters:

• toolName: string

Returns: void

listTools()

List all registered tools

listTools(): string[];

Returns: string[]

type: 'object';
properties?: Record<string, unknown>;
required?: string[];
[key: string]: unknown;

};` | JSON Schema for tool input |

type: 'text' | 'image' | 'resource';
text?: string;
data?: string;
mimeType?: string;
uri?: string;

}>;| Result content | |isError?|isError?: boolean;` | Whether the tool call resulted in an error |

always?: { read_only?: boolean; tool_names?: string[] };
never?: { read_only?: boolean; tool_names?: string[] };

} | null;| - | |defer_loading?|defer_loading?: boolean;| - | |headers?|headers?: Record<string, string> | null;| - | |server_description?|server_description?: string;` | - |

reportFailure()

Report an operational failure. First report wins; inactive after callback settlement.

reportFailure(error: Error): void;

Parameters:

• error: Error

Returns: void

execute()

execute(
    request: RemoteToolExecutionRequest,
    options?: { signal?: AbortSignal },
  ): Promise<RemoteToolExecutionResponse>;

Parameters:

• request: RemoteToolExecutionRequest
• options: { signal?: AbortSignal | undefined; } | undefined (optional)

Returns: Promise<RemoteToolExecutionResponse>

createAgent()

createAgent(): Agent | Promise<Agent>;

Returns: Agent | Promise<Agent>

resolveExecution()?

resolveExecution?(args: Record<string, unknown>, context: ToolContext | undefined): ExecutionBinding;

Parameters:

• args: Record<string, unknown>
• context: ToolContext | undefined

Returns: ExecutionBinding

• When set: the per-tool targetUser schema parameter is OMITTED and this value is always used.
• When unset: existing behavior (LLM supplies targetUser for app-only auth).
• Silently ignored for delegated connectors (identity already bound by token). |

name: string;
arguments: string; // JSON string

};| - | |async?|async?: boolean;| Whether the provider marked this as an async protocol call. | |blocking|blocking: boolean;| - | |state|state: ToolCallState;| - | |startTime?|startTime?: Date;| - | |endTime?|endTime?: Date;| - | |error?|error?: string;` | - |