@openai/agents-core
Version:
The OpenAI Agents SDK is a lightweight yet powerful framework for building multi-agent workflows.
389 lines • 15.1 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.FUNCTION_TOOL_NAMESPACE_DESCRIPTION = exports.FUNCTION_TOOL_NAMESPACE = exports.toolQualifiedName = exports.toolDisplayName = void 0;
exports.bindMcpTool = bindMcpTool;
exports.getMcpToolBinding = getMcpToolBinding;
exports.matchesFunctionToolRecipient = matchesFunctionToolRecipient;
exports.getHostedMcpApprovalRequestIdentity = getHostedMcpApprovalRequestIdentity;
exports.getHostedMcpApprovalStateKey = getHostedMcpApprovalStateKey;
exports.getHostedMcpApprovalRequestKey = getHostedMcpApprovalRequestKey;
exports.getHostedMcpApprovalIdentityFromStateKey = getHostedMcpApprovalIdentityFromStateKey;
exports.getToolCallNamespace = getToolCallNamespace;
exports.getToolCallName = getToolCallName;
exports.getToolCallQualifiedName = getToolCallQualifiedName;
exports.getToolCallDisplayName = getToolCallDisplayName;
exports.getFunctionToolLookupKey = getFunctionToolLookupKey;
exports.getFunctionToolLookupKeyForCall = getFunctionToolLookupKeyForCall;
exports.isDeferredTopLevelFunctionTool = isDeferredTopLevelFunctionTool;
exports.getBareTopLevelFunctionToolName = getBareTopLevelFunctionToolName;
exports.getFunctionToolLookupKeyForTool = getFunctionToolLookupKeyForTool;
exports.assertFunctionToolLookupConfiguration = assertFunctionToolLookupConfiguration;
exports.buildFunctionToolLookupMap = buildFunctionToolLookupMap;
exports.resolveFunctionToolCall = resolveFunctionToolCall;
exports.getFunctionToolStateKey = getFunctionToolStateKey;
exports.getFunctionToolLegacyStateKeyFromStateKey = getFunctionToolLegacyStateKeyFromStateKey;
exports.getFunctionToolStateKeyForCall = getFunctionToolStateKeyForCall;
exports.getFunctionToolStateKeyForResolvedCall = getFunctionToolStateKeyForResolvedCall;
exports.getFunctionToolStateKeys = getFunctionToolStateKeys;
exports.getExplicitFunctionToolNamespace = getExplicitFunctionToolNamespace;
exports.getFunctionToolNamespace = getFunctionToolNamespace;
exports.getFunctionToolNamespaceDescription = getFunctionToolNamespaceDescription;
exports.getFunctionToolQualifiedName = getFunctionToolQualifiedName;
exports.getFunctionToolDisplayName = getFunctionToolDisplayName;
exports.matchesFunctionToolName = matchesFunctionToolName;
const errors_1 = require("./errors.js");
const tooling_1 = require("./tooling.js");
var tooling_2 = require("./tooling.js");
Object.defineProperty(exports, "toolDisplayName", { enumerable: true, get: function () { return tooling_2.toolDisplayName; } });
Object.defineProperty(exports, "toolQualifiedName", { enumerable: true, get: function () { return tooling_2.toolQualifiedName; } });
// Key by the invocation function so supported namespace/preparation copies retain identity.
const mcpToolBindings = new WeakMap();
/** @internal */
function bindMcpTool(tool, binding) {
mcpToolBindings.set(tool.invoke, Object.freeze({ ...binding }));
return tool;
}
/** @internal */
function getMcpToolBinding(tool) {
return mcpToolBindings.get(tool.invoke) ?? null;
}
/** @internal */
function matchesFunctionToolRecipient(original, tool) {
const current = getMcpToolBinding(tool);
if (original === 'unknown')
return false;
if (original === null || current === null)
return original === current;
return (original.serverName === current.serverName &&
original.toolName === current.toolName &&
original.serverIndex === current.serverIndex);
}
exports.FUNCTION_TOOL_NAMESPACE = Symbol('functionToolNamespace');
exports.FUNCTION_TOOL_NAMESPACE_DESCRIPTION = Symbol('functionToolNamespaceDescription');
function isNonEmptyString(value) {
return typeof value === 'string' && value.length > 0;
}
/** @internal */
function getHostedMcpApprovalRequestIdentity(value) {
const candidate = value;
const rawItem = candidate?.rawItem && typeof candidate.rawItem === 'object'
? candidate.rawItem
: candidate;
if (rawItem?.type !== 'hosted_tool_call') {
return undefined;
}
const providerData = rawItem.providerData;
if (!providerData) {
return undefined;
}
if (providerData.type !== undefined &&
providerData.type !== 'mcp_approval_request') {
return undefined;
}
if (providerData.type === undefined &&
!isNonEmptyString(providerData.server_label) &&
!(isNonEmptyString(providerData.serverLabel) &&
isNonEmptyString(providerData.itemId))) {
return undefined;
}
return {
...(isNonEmptyString(providerData.id)
? { requestId: providerData.id }
: isNonEmptyString(providerData.itemId)
? { requestId: providerData.itemId }
: isNonEmptyString(rawItem.id)
? { requestId: rawItem.id }
: {}),
...(isNonEmptyString(providerData.server_label)
? { serverLabel: providerData.server_label }
: isNonEmptyString(providerData.serverLabel)
? { serverLabel: providerData.serverLabel }
: {}),
...(isNonEmptyString(providerData.name)
? { toolName: providerData.name }
: isNonEmptyString(rawItem.name) &&
rawItem.name !== 'mcp_approval_request'
? { toolName: rawItem.name }
: {}),
};
}
/** @internal */
function getHostedMcpApprovalStateKey(identity) {
if (identity.serverLabel && identity.toolName) {
return JSON.stringify([
'hosted_mcp',
identity.serverLabel,
identity.toolName,
]);
}
return undefined;
}
/** @internal */
function getHostedMcpApprovalRequestKey(identity) {
if (identity.serverLabel && identity.toolName && identity.requestId) {
return JSON.stringify([
'hosted_mcp_request',
identity.serverLabel,
identity.toolName,
identity.requestId,
]);
}
return undefined;
}
/** @internal */
function getHostedMcpApprovalIdentityFromStateKey(stateKey) {
try {
const value = JSON.parse(stateKey);
if (Array.isArray(value) &&
value.length === 3 &&
value[0] === 'hosted_mcp' &&
isNonEmptyString(value[1]) &&
isNonEmptyString(value[2])) {
return { serverLabel: value[1], toolName: value[2] };
}
}
catch {
// Non-JSON keys are not hosted MCP approval identities.
}
return undefined;
}
function encodeFunctionToolLookupKey(parts) {
return JSON.stringify(parts);
}
function getToolCallNamespace(toolCall) {
return isNonEmptyString(toolCall.namespace) ? toolCall.namespace : undefined;
}
function getToolCallName(toolCall) {
return isNonEmptyString(toolCall.name) ? toolCall.name : undefined;
}
function getToolCallQualifiedName(toolCall) {
return (0, tooling_1.toolQualifiedName)(getToolCallName(toolCall), getToolCallNamespace(toolCall));
}
function getToolCallDisplayName(toolCall) {
return (0, tooling_1.toolDisplayName)(getToolCallName(toolCall), getToolCallNamespace(toolCall));
}
/** @internal */
function getFunctionToolLookupKey(name, namespace) {
if (!isNonEmptyString(name)) {
return undefined;
}
if (namespace === name) {
return encodeFunctionToolLookupKey(['deferred_top_level', name]);
}
if (isNonEmptyString(namespace)) {
return encodeFunctionToolLookupKey(['namespaced', namespace, name]);
}
return encodeFunctionToolLookupKey(['bare', name]);
}
/** @internal */
function getFunctionToolLookupKeyForCall(toolCall) {
return getFunctionToolLookupKey(getToolCallName(toolCall), getToolCallNamespace(toolCall));
}
/** @internal */
function isDeferredTopLevelFunctionTool(tool) {
const candidate = tool;
return (candidate?.deferLoading === true &&
!getExplicitFunctionToolNamespace(tool) &&
isNonEmptyString(candidate?.name));
}
/** @internal */
function getBareTopLevelFunctionToolName(tool) {
const name = getFunctionToolName(tool);
if (!name ||
getExplicitFunctionToolNamespace(tool) ||
isDeferredTopLevelFunctionTool(tool)) {
return undefined;
}
return name;
}
/** @internal */
function getFunctionToolLookupKeyForTool(tool) {
const name = getFunctionToolName(tool);
if (isDeferredTopLevelFunctionTool(tool)) {
return encodeFunctionToolLookupKey(['deferred_top_level', name]);
}
return getFunctionToolLookupKey(name, getExplicitFunctionToolNamespace(tool));
}
/** @internal */
function assertFunctionToolLookupConfiguration(tools) {
const strictOwners = new Map();
for (const tool of tools) {
const name = getFunctionToolName(tool);
const namespace = getExplicitFunctionToolNamespace(tool);
if (name && namespace === name) {
throw new errors_1.UserError('Responses tool search reserves same-name namespaces for deferred top-level function tools. Rename the namespace or tool name to avoid ambiguous dispatch.');
}
if (!namespace && !isDeferredTopLevelFunctionTool(tool)) {
continue;
}
const key = getFunctionToolLookupKeyForTool(tool);
if (!key) {
continue;
}
if (strictOwners.has(key)) {
throw new errors_1.UserError('Ambiguous function tool configuration. Assign unique names within each namespace and for deferred top-level tools.');
}
strictOwners.set(key, tool);
}
}
/** @internal */
function buildFunctionToolLookupMap(tools) {
assertFunctionToolLookupConfiguration(tools);
const lookup = new Map();
for (const tool of tools) {
const key = getFunctionToolLookupKeyForTool(tool);
if (key) {
lookup.set(key, tool);
}
}
return lookup;
}
/** @internal */
function resolveFunctionToolCall(toolCall, availableTools) {
const key = getFunctionToolLookupKeyForCall(toolCall);
const directMatch = key ? availableTools.get(key) : undefined;
if (directMatch || getToolCallNamespace(toolCall)) {
return directMatch;
}
const name = getToolCallName(toolCall);
const deferredKey = name
? encodeFunctionToolLookupKey(['deferred_top_level', name])
: undefined;
const deferredMatch = deferredKey
? availableTools.get(deferredKey)
: undefined;
if (deferredMatch || !name) {
return deferredMatch;
}
let flattenedNamespaceMatch;
for (const tool of availableTools.values()) {
if (!getExplicitFunctionToolNamespace(tool) ||
getFunctionToolQualifiedName(tool) !== name) {
continue;
}
if (flattenedNamespaceMatch && flattenedNamespaceMatch !== tool) {
return undefined;
}
flattenedNamespaceMatch = tool;
}
return flattenedNamespaceMatch;
}
/** @internal */
function getFunctionToolStateKey(tool) {
const name = getFunctionToolName(tool);
if (!name) {
return undefined;
}
return getFunctionToolLookupKeyForTool(tool);
}
/** @internal */
function getFunctionToolLegacyStateKeyFromStateKey(stateKey) {
let parts;
try {
parts = JSON.parse(stateKey);
}
catch {
return undefined;
}
if (!Array.isArray(parts)) {
return undefined;
}
if ((parts[0] === 'bare' || parts[0] === 'deferred_top_level') &&
parts.length === 2 &&
isNonEmptyString(parts[1])) {
return parts[1];
}
if (parts[0] === 'namespaced' &&
parts.length === 3 &&
isNonEmptyString(parts[1]) &&
isNonEmptyString(parts[2])) {
return (0, tooling_1.toolQualifiedName)(parts[2], parts[1]);
}
return undefined;
}
/** @internal */
function getFunctionToolStateKeyForCall(toolCall, fallbackName) {
const name = getToolCallName(toolCall);
const namespace = getToolCallNamespace(toolCall);
return (getFunctionToolLookupKey(name ?? fallbackName, namespace) ?? fallbackName);
}
/** @internal */
function getFunctionToolStateKeyForResolvedCall(toolCall, tool, resolvedToolStateKey = getFunctionToolStateKey(tool)) {
const callStateKey = getFunctionToolStateKeyForCall(toolCall);
if (!callStateKey || !resolvedToolStateKey) {
return undefined;
}
if (callStateKey === resolvedToolStateKey) {
return resolvedToolStateKey;
}
return !getToolCallNamespace(toolCall) &&
isDeferredTopLevelFunctionTool(tool) &&
getToolCallName(toolCall) === getFunctionToolName(tool)
? resolvedToolStateKey
: undefined;
}
/** @internal */
function getFunctionToolStateKeys(tool, availableTools = []) {
const primary = getFunctionToolStateKey(tool);
if (!primary) {
return [];
}
const name = getFunctionToolName(tool);
if (!name) {
return [primary];
}
const legacyKey = getFunctionToolLegacyStateKey(tool);
if (!legacyKey || legacyKey === primary) {
return [primary];
}
const hasLegacyCollision = availableTools.some((candidate) => candidate !== tool &&
getFunctionToolLegacyStateKey(candidate) === legacyKey &&
getFunctionToolStateKey(candidate) !== primary);
return hasLegacyCollision ? [primary] : [primary, legacyKey];
}
function getFunctionToolLegacyStateKey(tool) {
const name = getFunctionToolName(tool);
if (!name) {
return undefined;
}
const namespace = getExplicitFunctionToolNamespace(tool);
return namespace ? (0, tooling_1.toolQualifiedName)(name, namespace) : name;
}
function getExplicitFunctionToolNamespace(tool) {
const candidate = tool;
return isNonEmptyString(candidate?.[exports.FUNCTION_TOOL_NAMESPACE])
? candidate[exports.FUNCTION_TOOL_NAMESPACE]
: undefined;
}
function getFunctionToolNamespace(tool) {
return getExplicitFunctionToolNamespace(tool);
}
function getFunctionToolNamespaceDescription(tool) {
const candidate = tool;
return isNonEmptyString(candidate?.[exports.FUNCTION_TOOL_NAMESPACE_DESCRIPTION])
? candidate[exports.FUNCTION_TOOL_NAMESPACE_DESCRIPTION]
: undefined;
}
function getFunctionToolQualifiedName(tool) {
const candidate = tool;
return (0, tooling_1.toolQualifiedName)(isNonEmptyString(candidate?.name) ? candidate.name : undefined, getFunctionToolNamespace(tool));
}
function getFunctionToolDisplayName(tool) {
const candidate = tool;
return (0, tooling_1.toolDisplayName)(isNonEmptyString(candidate?.name) ? candidate.name : undefined, getFunctionToolNamespace(tool));
}
function matchesFunctionToolName(tool, candidate) {
if (!isNonEmptyString(candidate)) {
return false;
}
const bareName = getFunctionToolName(tool);
if (bareName === candidate) {
return true;
}
return getFunctionToolQualifiedName(tool) === candidate;
}
function getFunctionToolName(tool) {
const candidate = tool;
return isNonEmptyString(candidate?.name) ? candidate.name : undefined;
}
//# sourceMappingURL=toolIdentity.js.map