1179 lines
35 KiB
TypeScript
1179 lines
35 KiB
TypeScript
import { getDisplayableToolReturn } from "../agent/approval-execution";
|
|
import { getModelInfo } from "../agent/model";
|
|
import { getAllSubagentConfigs } from "../agent/subagents";
|
|
import { INTERRUPTED_BY_USER } from "../constants";
|
|
import {
|
|
runPostToolUseFailureHooks,
|
|
runPostToolUseHooks,
|
|
runPreToolUseHooks,
|
|
} from "../hooks";
|
|
import { telemetry } from "../telemetry";
|
|
import { TOOL_DEFINITIONS, type ToolName } from "./toolDefinitions";
|
|
|
|
export const TOOL_NAMES = Object.keys(TOOL_DEFINITIONS) as ToolName[];
|
|
const STREAMING_SHELL_TOOLS = new Set([
|
|
"Bash",
|
|
"shell_command",
|
|
"ShellCommand",
|
|
"shell",
|
|
"Shell",
|
|
"run_shell_command",
|
|
"RunShellCommand",
|
|
]);
|
|
|
|
// Maps internal tool names to server/model-facing tool names
|
|
// This allows us to have multiple implementations (e.g., write_file_gemini, Write from Anthropic)
|
|
// that map to the same server tool name since only one toolset is active at a time
|
|
const TOOL_NAME_MAPPINGS: Partial<Record<ToolName, string>> = {
|
|
// Gemini tools - map to their original Gemini CLI names
|
|
glob_gemini: "glob",
|
|
write_todos: "write_todos",
|
|
write_file_gemini: "write_file",
|
|
replace: "replace",
|
|
search_file_content: "search_file_content",
|
|
read_many_files: "read_many_files",
|
|
read_file_gemini: "read_file",
|
|
list_directory: "list_directory",
|
|
run_shell_command: "run_shell_command",
|
|
};
|
|
|
|
/**
|
|
* Get the server-facing name for a tool (maps internal names to what the model sees)
|
|
*/
|
|
export function getServerToolName(internalName: string): string {
|
|
return TOOL_NAME_MAPPINGS[internalName as ToolName] || internalName;
|
|
}
|
|
|
|
/**
|
|
* Get the internal tool name from a server-facing name
|
|
* Used when the server sends back tool calls/approvals with server names
|
|
*/
|
|
export function getInternalToolName(serverName: string): string {
|
|
// Build reverse mapping
|
|
for (const [internal, server] of Object.entries(TOOL_NAME_MAPPINGS)) {
|
|
if (server === serverName) {
|
|
return internal;
|
|
}
|
|
}
|
|
// If not in mapping, the server name is the internal name
|
|
return serverName;
|
|
}
|
|
|
|
export const ANTHROPIC_DEFAULT_TOOLS: ToolName[] = [
|
|
"AskUserQuestion",
|
|
"Bash",
|
|
"BashOutput",
|
|
"Edit",
|
|
"EnterPlanMode",
|
|
"ExitPlanMode",
|
|
"Glob",
|
|
"Grep",
|
|
"KillBash",
|
|
// "MultiEdit",
|
|
// "LS",
|
|
"Read",
|
|
"Skill",
|
|
"Task",
|
|
"TodoWrite",
|
|
"Write",
|
|
];
|
|
|
|
export const OPENAI_DEFAULT_TOOLS: ToolName[] = [
|
|
"shell_command",
|
|
"shell",
|
|
"read_file",
|
|
"list_dir",
|
|
"grep_files",
|
|
"apply_patch",
|
|
"update_plan",
|
|
"view_image",
|
|
"Skill",
|
|
"Task",
|
|
];
|
|
|
|
export const GEMINI_DEFAULT_TOOLS: ToolName[] = [
|
|
"run_shell_command",
|
|
"read_file_gemini",
|
|
"list_directory",
|
|
"glob_gemini",
|
|
"search_file_content",
|
|
"replace",
|
|
"write_file_gemini",
|
|
"write_todos",
|
|
"read_many_files",
|
|
"Skill",
|
|
"Task",
|
|
];
|
|
|
|
// PascalCase toolsets (codex-2 and gemini-2) for consistency with Skill tool naming
|
|
export const OPENAI_PASCAL_TOOLS: ToolName[] = [
|
|
// Additional Letta Code tools
|
|
"AskUserQuestion",
|
|
"EnterPlanMode",
|
|
"ExitPlanMode",
|
|
"Task",
|
|
"Skill",
|
|
// Standard Codex tools
|
|
"ShellCommand",
|
|
"Shell",
|
|
"ReadFile",
|
|
"view_image",
|
|
"ListDir",
|
|
"GrepFiles",
|
|
"ApplyPatch",
|
|
"UpdatePlan",
|
|
];
|
|
|
|
export const GEMINI_PASCAL_TOOLS: ToolName[] = [
|
|
// Additional Letta Code tools
|
|
"AskUserQuestion",
|
|
"EnterPlanMode",
|
|
"ExitPlanMode",
|
|
"Skill",
|
|
"Task",
|
|
// Standard Gemini tools
|
|
"RunShellCommand",
|
|
"ReadFileGemini",
|
|
"ListDirectory",
|
|
"GlobGemini",
|
|
"SearchFileContent",
|
|
"Replace",
|
|
"WriteFileGemini",
|
|
"WriteTodos",
|
|
"ReadManyFiles",
|
|
];
|
|
|
|
// Tool permissions configuration
|
|
const TOOL_PERMISSIONS: Record<ToolName, { requiresApproval: boolean }> = {
|
|
AskUserQuestion: { requiresApproval: true },
|
|
Bash: { requiresApproval: true },
|
|
BashOutput: { requiresApproval: false },
|
|
Edit: { requiresApproval: true },
|
|
EnterPlanMode: { requiresApproval: true },
|
|
ExitPlanMode: { requiresApproval: false },
|
|
Glob: { requiresApproval: false },
|
|
Grep: { requiresApproval: false },
|
|
KillBash: { requiresApproval: true },
|
|
LS: { requiresApproval: false },
|
|
MultiEdit: { requiresApproval: true },
|
|
Read: { requiresApproval: false },
|
|
view_image: { requiresApproval: false },
|
|
ReadLSP: { requiresApproval: false },
|
|
Skill: { requiresApproval: false },
|
|
Task: { requiresApproval: true },
|
|
TodoWrite: { requiresApproval: false },
|
|
Write: { requiresApproval: true },
|
|
shell_command: { requiresApproval: true },
|
|
shell: { requiresApproval: true },
|
|
read_file: { requiresApproval: false },
|
|
list_dir: { requiresApproval: false },
|
|
grep_files: { requiresApproval: false },
|
|
apply_patch: { requiresApproval: true },
|
|
update_plan: { requiresApproval: false },
|
|
// Gemini toolset
|
|
glob_gemini: { requiresApproval: false },
|
|
list_directory: { requiresApproval: false },
|
|
read_file_gemini: { requiresApproval: false },
|
|
read_many_files: { requiresApproval: false },
|
|
replace: { requiresApproval: true },
|
|
run_shell_command: { requiresApproval: true },
|
|
search_file_content: { requiresApproval: false },
|
|
write_todos: { requiresApproval: false },
|
|
write_file_gemini: { requiresApproval: true },
|
|
// Codex-2 toolset (PascalCase)
|
|
ShellCommand: { requiresApproval: true },
|
|
Shell: { requiresApproval: true },
|
|
ReadFile: { requiresApproval: false },
|
|
ListDir: { requiresApproval: false },
|
|
GrepFiles: { requiresApproval: false },
|
|
ApplyPatch: { requiresApproval: true },
|
|
UpdatePlan: { requiresApproval: false },
|
|
// Gemini-2 toolset (PascalCase)
|
|
RunShellCommand: { requiresApproval: true },
|
|
ReadFileGemini: { requiresApproval: false },
|
|
ListDirectory: { requiresApproval: false },
|
|
GlobGemini: { requiresApproval: false },
|
|
SearchFileContent: { requiresApproval: false },
|
|
Replace: { requiresApproval: true },
|
|
WriteFileGemini: { requiresApproval: true },
|
|
WriteTodos: { requiresApproval: false },
|
|
ReadManyFiles: { requiresApproval: false },
|
|
};
|
|
|
|
interface JsonSchema {
|
|
properties?: Record<string, JsonSchema>;
|
|
required?: string[];
|
|
[key: string]: unknown;
|
|
}
|
|
|
|
type ToolArgs = Record<string, unknown>;
|
|
|
|
interface ToolSchema {
|
|
name: string;
|
|
description: string;
|
|
input_schema: JsonSchema;
|
|
}
|
|
|
|
interface ToolDefinition {
|
|
schema: ToolSchema;
|
|
fn: (args: ToolArgs) => Promise<unknown>;
|
|
}
|
|
|
|
import type {
|
|
ImageContent,
|
|
TextContent,
|
|
} from "@letta-ai/letta-client/resources/agents/messages";
|
|
|
|
// Tool return content can be a string or array of text/image content parts
|
|
export type ToolReturnContent = string | Array<TextContent | ImageContent>;
|
|
|
|
export type ToolExecutionResult = {
|
|
toolReturn: ToolReturnContent;
|
|
status: "success" | "error";
|
|
stdout?: string[];
|
|
stderr?: string[];
|
|
};
|
|
|
|
type ToolRegistry = Map<string, ToolDefinition>;
|
|
|
|
// Use globalThis to ensure singleton across bundle duplicates
|
|
// This prevents Bun's bundler from creating duplicate instances
|
|
const REGISTRY_KEY = Symbol.for("@letta/toolRegistry");
|
|
const SWITCH_LOCK_KEY = Symbol.for("@letta/toolSwitchLock");
|
|
|
|
interface SwitchLockState {
|
|
promise: Promise<void> | null;
|
|
resolve: (() => void) | null;
|
|
refCount: number; // Ref-counted to handle overlapping switches
|
|
}
|
|
|
|
type GlobalWithToolState = typeof globalThis & {
|
|
[REGISTRY_KEY]?: ToolRegistry;
|
|
[SWITCH_LOCK_KEY]?: SwitchLockState;
|
|
};
|
|
|
|
function getRegistry(): ToolRegistry {
|
|
const global = globalThis as GlobalWithToolState;
|
|
if (!global[REGISTRY_KEY]) {
|
|
global[REGISTRY_KEY] = new Map();
|
|
}
|
|
return global[REGISTRY_KEY];
|
|
}
|
|
|
|
function getSwitchLock(): SwitchLockState {
|
|
const global = globalThis as GlobalWithToolState;
|
|
if (!global[SWITCH_LOCK_KEY]) {
|
|
global[SWITCH_LOCK_KEY] = { promise: null, resolve: null, refCount: 0 };
|
|
}
|
|
return global[SWITCH_LOCK_KEY];
|
|
}
|
|
|
|
const toolRegistry = getRegistry();
|
|
|
|
/**
|
|
* Acquires the toolset switch lock. Call before starting async tool loading.
|
|
* Ref-counted: multiple overlapping switches will keep the lock held until all complete.
|
|
* Any calls to waitForToolsetReady() will block until all switches finish.
|
|
*/
|
|
function acquireSwitchLock(): void {
|
|
const lock = getSwitchLock();
|
|
lock.refCount++;
|
|
|
|
// Only create a new promise if this is the first acquirer
|
|
if (lock.refCount === 1) {
|
|
lock.promise = new Promise((resolve) => {
|
|
lock.resolve = resolve;
|
|
});
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Releases the toolset switch lock. Call after atomic registry swap completes.
|
|
* Only actually releases when all acquirers have released (ref-count drops to 0).
|
|
*/
|
|
function releaseSwitchLock(): void {
|
|
const lock = getSwitchLock();
|
|
|
|
if (lock.refCount > 0) {
|
|
lock.refCount--;
|
|
}
|
|
|
|
// Only resolve when all switches are done
|
|
if (lock.refCount === 0 && lock.resolve) {
|
|
lock.resolve();
|
|
lock.promise = null;
|
|
lock.resolve = null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Waits for any in-progress toolset switch to complete.
|
|
* Call this before reading from the registry to ensure you get the final toolset.
|
|
* Returns immediately if no switch is in progress.
|
|
*/
|
|
export async function waitForToolsetReady(): Promise<void> {
|
|
const lock = getSwitchLock();
|
|
if (lock.promise) {
|
|
await lock.promise;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Checks if a toolset switch is currently in progress.
|
|
* Useful for synchronous checks where awaiting isn't possible.
|
|
*/
|
|
export function isToolsetSwitchInProgress(): boolean {
|
|
return getSwitchLock().refCount > 0;
|
|
}
|
|
|
|
/**
|
|
* Resolve a server/visible tool name to an internal tool name
|
|
* based on the currently loaded toolset.
|
|
*
|
|
* - If a tool with the exact name is loaded, prefer that.
|
|
* - Otherwise, fall back to the alias mapping used for Gemini tools.
|
|
* - Returns undefined if no matching tool is loaded.
|
|
*/
|
|
function resolveInternalToolName(name: string): string | undefined {
|
|
if (toolRegistry.has(name)) {
|
|
return name;
|
|
}
|
|
|
|
const internalName = getInternalToolName(name);
|
|
if (toolRegistry.has(internalName)) {
|
|
return internalName;
|
|
}
|
|
|
|
return undefined;
|
|
}
|
|
|
|
/**
|
|
* ClientTool interface matching the Letta SDK's expected format.
|
|
* Used when passing client-side tools via the client_tools field.
|
|
*/
|
|
export interface ClientTool {
|
|
name: string;
|
|
description?: string | null;
|
|
parameters?: { [key: string]: unknown } | null;
|
|
}
|
|
|
|
/**
|
|
* Get all loaded tools in the format expected by the Letta API's client_tools field.
|
|
* Maps internal tool names to server-facing names for proper tool invocation.
|
|
*/
|
|
export function getClientToolsFromRegistry(): ClientTool[] {
|
|
return Array.from(toolRegistry.entries()).map(([name, tool]) => {
|
|
const serverName = getServerToolName(name);
|
|
return {
|
|
name: serverName,
|
|
description: tool.schema.description,
|
|
parameters: tool.schema.input_schema,
|
|
};
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Get permissions for a specific tool.
|
|
* @param toolName - The name of the tool
|
|
* @returns Tool permissions object with requiresApproval flag
|
|
*/
|
|
export function getToolPermissions(toolName: string) {
|
|
return TOOL_PERMISSIONS[toolName as ToolName] || { requiresApproval: false };
|
|
}
|
|
|
|
/**
|
|
* Check if a tool requires approval before execution.
|
|
* @param toolName - The name of the tool
|
|
* @returns true if the tool requires approval, false otherwise
|
|
* @deprecated Use checkToolPermission instead for full permission system support
|
|
*/
|
|
export function requiresApproval(toolName: string): boolean {
|
|
return TOOL_PERMISSIONS[toolName as ToolName]?.requiresApproval ?? false;
|
|
}
|
|
|
|
/**
|
|
* Check permission for a tool execution using the full permission system.
|
|
* @param toolName - Name of the tool
|
|
* @param toolArgs - Tool arguments
|
|
* @param workingDirectory - Current working directory (defaults to process.cwd())
|
|
* @returns Permission decision: "allow", "deny", or "ask"
|
|
*/
|
|
export async function checkToolPermission(
|
|
toolName: string,
|
|
toolArgs: ToolArgs,
|
|
workingDirectory: string = process.cwd(),
|
|
): Promise<{
|
|
decision: "allow" | "deny" | "ask";
|
|
matchedRule?: string;
|
|
reason?: string;
|
|
}> {
|
|
const { checkPermissionWithHooks } = await import("../permissions/checker");
|
|
const { loadPermissions } = await import("../permissions/loader");
|
|
|
|
const permissions = await loadPermissions(workingDirectory);
|
|
return checkPermissionWithHooks(
|
|
toolName,
|
|
toolArgs,
|
|
permissions,
|
|
workingDirectory,
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Save a permission rule to settings
|
|
* @param rule - Permission rule (e.g., "Read(src/**)")
|
|
* @param ruleType - Type of rule ("allow", "deny", or "ask")
|
|
* @param scope - Where to save ("project", "local", "user", or "session")
|
|
* @param workingDirectory - Current working directory
|
|
*/
|
|
export async function savePermissionRule(
|
|
rule: string,
|
|
ruleType: "allow" | "deny" | "ask",
|
|
scope: "project" | "local" | "user" | "session",
|
|
workingDirectory: string = process.cwd(),
|
|
): Promise<void> {
|
|
// Handle session-only permissions
|
|
if (scope === "session") {
|
|
const { sessionPermissions } = await import("../permissions/session");
|
|
sessionPermissions.addRule(rule, ruleType);
|
|
return;
|
|
}
|
|
|
|
// Handle persisted permissions
|
|
const { savePermissionRule: save } = await import("../permissions/loader");
|
|
await save(rule, ruleType, scope, workingDirectory);
|
|
}
|
|
|
|
/**
|
|
* Analyze approval context for a tool execution
|
|
* @param toolName - Name of the tool
|
|
* @param toolArgs - Tool arguments
|
|
* @param workingDirectory - Current working directory
|
|
* @returns Approval context with recommended rule and button text
|
|
*/
|
|
export async function analyzeToolApproval(
|
|
toolName: string,
|
|
toolArgs: ToolArgs,
|
|
workingDirectory: string = process.cwd(),
|
|
): Promise<import("../permissions/analyzer").ApprovalContext> {
|
|
const { analyzeApprovalContext } = await import("../permissions/analyzer");
|
|
return analyzeApprovalContext(toolName, toolArgs, workingDirectory);
|
|
}
|
|
|
|
/**
|
|
* Atomically replaces the tool registry contents.
|
|
* This ensures no intermediate state where registry is empty or partial.
|
|
*
|
|
* @param newTools - Map of tools to replace the registry with
|
|
*/
|
|
function replaceRegistry(newTools: ToolRegistry): void {
|
|
// Single sync block - no awaits, no yields, no interleaving possible
|
|
toolRegistry.clear();
|
|
for (const [key, value] of newTools) {
|
|
toolRegistry.set(key, value);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Loads specific tools by name into the registry.
|
|
* Used when resuming an agent to load only the tools attached to that agent.
|
|
*
|
|
* Acquires the toolset switch lock during loading to prevent message sends from
|
|
* reading stale tools. Callers should use waitForToolsetReady() before sending messages.
|
|
*
|
|
* @param toolNames - Array of specific tool names to load
|
|
*/
|
|
export async function loadSpecificTools(toolNames: string[]): Promise<void> {
|
|
// Acquire lock to signal that a switch is in progress
|
|
acquireSwitchLock();
|
|
|
|
try {
|
|
// Import filter once, outside the loop (avoids repeated async yields)
|
|
const { toolFilter } = await import("./filter");
|
|
|
|
// Build new registry in a temporary map (all async work happens here)
|
|
const newRegistry: ToolRegistry = new Map();
|
|
|
|
for (const name of toolNames) {
|
|
// Skip if tool filter is active and this tool is not enabled
|
|
if (!toolFilter.isEnabled(name)) {
|
|
continue;
|
|
}
|
|
|
|
// Map server-facing name to our internal tool name
|
|
const internalName = getInternalToolName(name);
|
|
|
|
const definition = TOOL_DEFINITIONS[internalName as ToolName];
|
|
if (!definition) {
|
|
console.warn(
|
|
`Tool ${name} (internal: ${internalName}) not found in definitions, skipping`,
|
|
);
|
|
continue;
|
|
}
|
|
|
|
if (!definition.impl) {
|
|
throw new Error(`Tool implementation not found for ${internalName}`);
|
|
}
|
|
|
|
const toolSchema: ToolSchema = {
|
|
name: internalName,
|
|
description: definition.description,
|
|
input_schema: definition.schema,
|
|
};
|
|
|
|
// Add to temporary registry
|
|
newRegistry.set(internalName, {
|
|
schema: toolSchema,
|
|
fn: definition.impl,
|
|
});
|
|
}
|
|
|
|
// Atomic swap - no yields between clear and populate
|
|
replaceRegistry(newRegistry);
|
|
} finally {
|
|
// Always release the lock, even if an error occurred
|
|
releaseSwitchLock();
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Loads all tools defined in TOOL_NAMES and constructs their full schemas + function references.
|
|
* This should be called on program startup.
|
|
* Will error if any expected tool files are missing.
|
|
*
|
|
* Acquires the toolset switch lock during loading to prevent message sends from
|
|
* reading stale tools. Callers should use waitForToolsetReady() before sending messages.
|
|
*
|
|
* @returns Promise that resolves when all tools are loaded
|
|
*/
|
|
export async function loadTools(modelIdentifier?: string): Promise<void> {
|
|
// Acquire lock to signal that a switch is in progress
|
|
acquireSwitchLock();
|
|
|
|
try {
|
|
const { toolFilter } = await import("./filter");
|
|
|
|
// Get all subagents (built-in + custom) to inject into Task description
|
|
const allSubagentConfigs = await getAllSubagentConfigs();
|
|
const discoveredSubagents = Object.entries(allSubagentConfigs).map(
|
|
([name, config]) => ({
|
|
name,
|
|
description: config.description,
|
|
recommendedModel: config.recommendedModel,
|
|
}),
|
|
);
|
|
const filterActive = toolFilter.isActive();
|
|
|
|
let baseToolNames: ToolName[];
|
|
if (!filterActive && modelIdentifier && isGeminiModel(modelIdentifier)) {
|
|
baseToolNames = GEMINI_PASCAL_TOOLS;
|
|
} else if (
|
|
!filterActive &&
|
|
modelIdentifier &&
|
|
isOpenAIModel(modelIdentifier)
|
|
) {
|
|
baseToolNames = OPENAI_PASCAL_TOOLS;
|
|
} else if (!filterActive) {
|
|
baseToolNames = ANTHROPIC_DEFAULT_TOOLS;
|
|
} else {
|
|
// When user explicitly sets --tools, respect that and allow any tool name
|
|
baseToolNames = TOOL_NAMES;
|
|
}
|
|
|
|
// Build new registry in a temporary map (all async work happens above)
|
|
const newRegistry: ToolRegistry = new Map();
|
|
|
|
for (const name of baseToolNames) {
|
|
if (!toolFilter.isEnabled(name)) {
|
|
continue;
|
|
}
|
|
|
|
try {
|
|
const definition = TOOL_DEFINITIONS[name];
|
|
if (!definition) {
|
|
throw new Error(`Missing tool definition for ${name}`);
|
|
}
|
|
|
|
if (!definition.impl) {
|
|
throw new Error(`Tool implementation not found for ${name}`);
|
|
}
|
|
|
|
// For Task tool, inject discovered subagent descriptions
|
|
let description = definition.description;
|
|
if (name === "Task" && discoveredSubagents.length > 0) {
|
|
description = injectSubagentsIntoTaskDescription(
|
|
description,
|
|
discoveredSubagents,
|
|
);
|
|
}
|
|
|
|
const toolSchema: ToolSchema = {
|
|
name,
|
|
description,
|
|
input_schema: definition.schema,
|
|
};
|
|
|
|
newRegistry.set(name, {
|
|
schema: toolSchema,
|
|
fn: definition.impl,
|
|
});
|
|
} catch (error) {
|
|
const message =
|
|
error instanceof Error ? error.message : JSON.stringify(error);
|
|
throw new Error(
|
|
`Required tool "${name}" could not be loaded from bundled assets. ${message}`,
|
|
);
|
|
}
|
|
}
|
|
|
|
// If LSP is enabled, swap Read with LSP-enhanced version
|
|
if (process.env.LETTA_ENABLE_LSP && newRegistry.has("Read")) {
|
|
const lspDefinition = TOOL_DEFINITIONS.ReadLSP;
|
|
if (lspDefinition) {
|
|
// Replace Read with ReadLSP (but keep the name "Read" for the agent)
|
|
newRegistry.set("Read", {
|
|
schema: {
|
|
name: "Read", // Keep the tool name as "Read" for the agent
|
|
description: lspDefinition.description,
|
|
input_schema: lspDefinition.schema,
|
|
},
|
|
fn: lspDefinition.impl,
|
|
});
|
|
}
|
|
}
|
|
|
|
// Atomic swap - no yields between clear and populate
|
|
replaceRegistry(newRegistry);
|
|
} finally {
|
|
// Always release the lock, even if an error occurred
|
|
releaseSwitchLock();
|
|
}
|
|
}
|
|
|
|
export function isOpenAIModel(modelIdentifier: string): boolean {
|
|
const info = getModelInfo(modelIdentifier);
|
|
if (info?.handle && typeof info.handle === "string") {
|
|
return info.handle.startsWith("openai/");
|
|
}
|
|
// Fallback: treat raw handle-style identifiers as OpenAI if they start with openai/
|
|
return modelIdentifier.startsWith("openai/");
|
|
}
|
|
|
|
export function isGeminiModel(modelIdentifier: string): boolean {
|
|
const info = getModelInfo(modelIdentifier);
|
|
if (info?.handle && typeof info.handle === "string") {
|
|
return (
|
|
info.handle.startsWith("google/") || info.handle.startsWith("google_ai/")
|
|
);
|
|
}
|
|
// Fallback: treat raw handle-style identifiers as Gemini
|
|
return (
|
|
modelIdentifier.startsWith("google/") ||
|
|
modelIdentifier.startsWith("google_ai/")
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Inject discovered subagent descriptions into the Task tool description
|
|
*/
|
|
function injectSubagentsIntoTaskDescription(
|
|
baseDescription: string,
|
|
subagents: Array<{
|
|
name: string;
|
|
description: string;
|
|
recommendedModel: string;
|
|
}>,
|
|
): string {
|
|
if (subagents.length === 0) {
|
|
return baseDescription;
|
|
}
|
|
|
|
// Build subagents section
|
|
const agentsSection = subagents
|
|
.map((agent) => {
|
|
return `### ${agent.name}
|
|
- **Purpose**: ${agent.description}
|
|
- **Recommended model**: ${agent.recommendedModel}`;
|
|
})
|
|
.join("\n\n");
|
|
|
|
// Insert before ## Usage section
|
|
const usageMarker = "## Usage";
|
|
const usageIndex = baseDescription.indexOf(usageMarker);
|
|
|
|
if (usageIndex === -1) {
|
|
// Fallback: append at the end
|
|
return `${baseDescription}\n\n## Available Agents\n\n${agentsSection}`;
|
|
}
|
|
|
|
// Insert agents section before ## Usage
|
|
const before = baseDescription.slice(0, usageIndex);
|
|
const after = baseDescription.slice(usageIndex);
|
|
|
|
return `${before}## Available Agents\n\n${agentsSection}\n\n${after}`;
|
|
}
|
|
|
|
/**
|
|
* Helper to clip tool return text to a reasonable display size
|
|
* Used by UI components to truncate long responses for display
|
|
*/
|
|
export function clipToolReturn(
|
|
text: string,
|
|
maxLines: number = 3,
|
|
maxChars: number = 300,
|
|
): string {
|
|
if (!text) return text;
|
|
|
|
// Don't clip user rejection reasons - they contain important feedback
|
|
// All denials use format: "Error: request to call tool denied. User reason: ..."
|
|
if (text.includes("request to call tool denied")) {
|
|
return text;
|
|
}
|
|
|
|
// First apply character limit to avoid extremely long text
|
|
let clipped = text;
|
|
if (text.length > maxChars) {
|
|
clipped = text.slice(0, maxChars);
|
|
}
|
|
|
|
// Then split into lines and limit line count
|
|
const lines = clipped.split("\n");
|
|
if (lines.length > maxLines) {
|
|
clipped = lines.slice(0, maxLines).join("\n");
|
|
}
|
|
|
|
// Add ellipsis if we truncated
|
|
if (text.length > maxChars || lines.length > maxLines) {
|
|
// Try to break at a word boundary if possible
|
|
const lastSpace = clipped.lastIndexOf(" ");
|
|
if (lastSpace > maxChars * 0.8) {
|
|
clipped = clipped.slice(0, lastSpace);
|
|
}
|
|
clipped += "…";
|
|
}
|
|
|
|
return clipped;
|
|
}
|
|
|
|
/**
|
|
* Flattens a tool response to a simple string format.
|
|
* Extracts the actual content from structured responses to match what the LLM expects.
|
|
*
|
|
* @param result - The raw result from a tool execution
|
|
* @returns A flattened string representation of the result
|
|
*/
|
|
function isRecord(value: unknown): value is Record<string, unknown> {
|
|
return typeof value === "object" && value !== null;
|
|
}
|
|
|
|
function isStringArray(value: unknown): value is string[] {
|
|
return (
|
|
Array.isArray(value) && value.every((item) => typeof item === "string")
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Check if an array contains multimodal content (text + images)
|
|
*/
|
|
function isMultimodalContent(
|
|
arr: unknown[],
|
|
): arr is Array<TextContent | ImageContent> {
|
|
return arr.every(
|
|
(item) => isRecord(item) && (item.type === "text" || item.type === "image"),
|
|
);
|
|
}
|
|
|
|
function flattenToolResponse(result: unknown): ToolReturnContent {
|
|
if (result === null || result === undefined) {
|
|
return "";
|
|
}
|
|
|
|
if (typeof result === "string") {
|
|
return result;
|
|
}
|
|
|
|
if (!isRecord(result)) {
|
|
return JSON.stringify(result);
|
|
}
|
|
|
|
if (typeof result.message === "string") {
|
|
return result.message;
|
|
}
|
|
|
|
// Check for multimodal content (images) - return as-is without flattening
|
|
if (Array.isArray(result.content) && isMultimodalContent(result.content)) {
|
|
return result.content;
|
|
}
|
|
|
|
if (typeof result.content === "string") {
|
|
return result.content;
|
|
}
|
|
|
|
if (Array.isArray(result.content)) {
|
|
const textContent = result.content
|
|
.filter(
|
|
(item): item is { type: string; text: string } =>
|
|
isRecord(item) &&
|
|
item.type === "text" &&
|
|
typeof item.text === "string",
|
|
)
|
|
.map((item) => item.text)
|
|
.join("\n");
|
|
|
|
if (textContent) {
|
|
return textContent;
|
|
}
|
|
}
|
|
|
|
if (typeof result.output === "string") {
|
|
return result.output;
|
|
}
|
|
|
|
if (Array.isArray(result.files)) {
|
|
const files = result.files.filter(
|
|
(file): file is string => typeof file === "string",
|
|
);
|
|
if (files.length === 0) {
|
|
return "No files found";
|
|
}
|
|
return `Found ${files.length} file${files.length === 1 ? "" : "s"}\n${files.join("\n")}`;
|
|
}
|
|
|
|
if (typeof result.killed === "boolean") {
|
|
return result.killed
|
|
? "Process killed successfully"
|
|
: "Failed to kill process (may have already exited)";
|
|
}
|
|
|
|
if (typeof result.error === "string") {
|
|
return result.error;
|
|
}
|
|
|
|
if (Array.isArray(result.todos)) {
|
|
return `Updated ${result.todos.length} todo${result.todos.length !== 1 ? "s" : ""}`;
|
|
}
|
|
|
|
return JSON.stringify(result);
|
|
}
|
|
|
|
/**
|
|
* Executes a tool by name with the provided arguments.
|
|
*
|
|
* @param name - The name of the tool to execute
|
|
* @param args - Arguments object to pass to the tool
|
|
* @param options - Optional execution options (abort signal, tool call ID, streaming callback)
|
|
* @returns Promise with the tool's execution result including status and optional stdout/stderr
|
|
*/
|
|
export async function executeTool(
|
|
name: string,
|
|
args: ToolArgs,
|
|
options?: {
|
|
signal?: AbortSignal;
|
|
toolCallId?: string;
|
|
onOutput?: (chunk: string, stream: "stdout" | "stderr") => void;
|
|
},
|
|
): Promise<ToolExecutionResult> {
|
|
const internalName = resolveInternalToolName(name);
|
|
if (!internalName) {
|
|
return {
|
|
toolReturn: `Tool not found: ${name}. Available tools: ${Array.from(toolRegistry.keys()).join(", ")}`,
|
|
status: "error",
|
|
};
|
|
}
|
|
|
|
const tool = toolRegistry.get(internalName);
|
|
if (!tool) {
|
|
return {
|
|
toolReturn: `Tool not found: ${name}. Available tools: ${Array.from(toolRegistry.keys()).join(", ")}`,
|
|
status: "error",
|
|
};
|
|
}
|
|
|
|
const startTime = Date.now();
|
|
|
|
// Run PreToolUse hooks - can block tool execution
|
|
const preHookResult = await runPreToolUseHooks(
|
|
internalName,
|
|
args as Record<string, unknown>,
|
|
options?.toolCallId,
|
|
);
|
|
if (preHookResult.blocked) {
|
|
const feedback = preHookResult.feedback.join("\n") || "Blocked by hook";
|
|
return {
|
|
toolReturn: `Error: Tool execution blocked by hook. ${feedback}`,
|
|
status: "error",
|
|
};
|
|
}
|
|
|
|
try {
|
|
// Inject options for tools that support them without altering schemas
|
|
let enhancedArgs = args;
|
|
|
|
if (STREAMING_SHELL_TOOLS.has(internalName)) {
|
|
if (options?.signal) {
|
|
enhancedArgs = { ...enhancedArgs, signal: options.signal };
|
|
}
|
|
if (options?.onOutput) {
|
|
enhancedArgs = { ...enhancedArgs, onOutput: options.onOutput };
|
|
}
|
|
}
|
|
|
|
// Inject toolCallId and abort signal for Task tool
|
|
if (internalName === "Task") {
|
|
if (options?.toolCallId) {
|
|
enhancedArgs = { ...enhancedArgs, toolCallId: options.toolCallId };
|
|
}
|
|
if (options?.signal) {
|
|
enhancedArgs = { ...enhancedArgs, signal: options.signal };
|
|
}
|
|
}
|
|
|
|
const result = await tool.fn(enhancedArgs);
|
|
const duration = Date.now() - startTime;
|
|
|
|
// Extract stdout/stderr if present (for bash tools)
|
|
const recordResult = isRecord(result) ? result : undefined;
|
|
const stdoutValue = recordResult?.stdout;
|
|
const stderrValue = recordResult?.stderr;
|
|
const stdout = isStringArray(stdoutValue) ? stdoutValue : undefined;
|
|
const stderr = isStringArray(stderrValue) ? stderrValue : undefined;
|
|
|
|
// Check if tool returned a status (e.g., Bash returns status: "error" on abort)
|
|
const toolStatus = recordResult?.status === "error" ? "error" : "success";
|
|
|
|
// Flatten the response to plain text
|
|
const flattenedResponse = flattenToolResponse(result);
|
|
|
|
// Track tool usage (calculate size for multimodal content)
|
|
const responseSize =
|
|
typeof flattenedResponse === "string"
|
|
? flattenedResponse.length
|
|
: JSON.stringify(flattenedResponse).length;
|
|
telemetry.trackToolUsage(
|
|
internalName,
|
|
toolStatus === "success",
|
|
duration,
|
|
responseSize,
|
|
toolStatus === "error" ? "tool_error" : undefined,
|
|
stderr ? stderr.join("\n") : undefined,
|
|
);
|
|
|
|
// Run PostToolUse hooks - exit 2 injects stderr into agent context
|
|
// Note: preceding_reasoning/assistant_message not available here - tracked in accumulator for server tools
|
|
let postToolUseFeedback: string[] = [];
|
|
try {
|
|
const postHookResult = await runPostToolUseHooks(
|
|
internalName,
|
|
args as Record<string, unknown>,
|
|
{
|
|
status: toolStatus,
|
|
output: getDisplayableToolReturn(flattenedResponse),
|
|
},
|
|
options?.toolCallId,
|
|
undefined, // workingDirectory
|
|
undefined, // agentId
|
|
undefined, // precedingReasoning - not available in tool manager context
|
|
undefined, // precedingAssistantMessage - not available in tool manager context
|
|
);
|
|
postToolUseFeedback = postHookResult.feedback;
|
|
} catch {
|
|
// Silently ignore hook errors - don't affect tool execution
|
|
}
|
|
|
|
// Run PostToolUseFailure hooks when tool returns error status
|
|
let postToolUseFailureFeedback: string[] = [];
|
|
if (toolStatus === "error") {
|
|
const errorOutput =
|
|
typeof flattenedResponse === "string"
|
|
? flattenedResponse
|
|
: JSON.stringify(flattenedResponse);
|
|
try {
|
|
const failureHookResult = await runPostToolUseFailureHooks(
|
|
internalName,
|
|
args as Record<string, unknown>,
|
|
errorOutput,
|
|
"tool_error", // error type for returned errors
|
|
options?.toolCallId,
|
|
undefined, // workingDirectory
|
|
undefined, // agentId
|
|
undefined, // precedingReasoning - not available in tool manager context
|
|
undefined, // precedingAssistantMessage - not available in tool manager context
|
|
);
|
|
postToolUseFailureFeedback = failureHookResult.feedback;
|
|
} catch {
|
|
// Silently ignore hook execution errors
|
|
}
|
|
}
|
|
|
|
// Combine feedback from both hook types and inject into tool return
|
|
const allFeedback = [...postToolUseFeedback, ...postToolUseFailureFeedback];
|
|
if (allFeedback.length > 0) {
|
|
const feedbackMessage = `\n\n[Hook feedback]:\n${allFeedback.join("\n")}`;
|
|
let finalToolReturn: ToolReturnContent;
|
|
if (typeof flattenedResponse === "string") {
|
|
finalToolReturn = flattenedResponse + feedbackMessage;
|
|
} else if (Array.isArray(flattenedResponse)) {
|
|
// Append feedback as a new text content block
|
|
finalToolReturn = [
|
|
...flattenedResponse,
|
|
{ type: "text" as const, text: feedbackMessage },
|
|
];
|
|
} else {
|
|
finalToolReturn = flattenedResponse;
|
|
}
|
|
return {
|
|
toolReturn: finalToolReturn,
|
|
status: toolStatus,
|
|
...(stdout && { stdout }),
|
|
...(stderr && { stderr }),
|
|
};
|
|
}
|
|
|
|
// Return the full response (truncation happens in UI layer only)
|
|
return {
|
|
toolReturn: flattenedResponse,
|
|
status: toolStatus,
|
|
...(stdout && { stdout }),
|
|
...(stderr && { stderr }),
|
|
};
|
|
} catch (error) {
|
|
const duration = Date.now() - startTime;
|
|
const isAbort =
|
|
error instanceof Error &&
|
|
(error.name === "AbortError" ||
|
|
error.message === "The operation was aborted" ||
|
|
// node:child_process AbortError may include code/message variants
|
|
("code" in error && error.code === "ABORT_ERR"));
|
|
const errorType = isAbort
|
|
? "abort"
|
|
: error instanceof Error
|
|
? error.name
|
|
: "unknown";
|
|
const errorMessage = isAbort
|
|
? INTERRUPTED_BY_USER
|
|
: error instanceof Error
|
|
? error.message
|
|
: String(error);
|
|
|
|
// Track tool usage error
|
|
telemetry.trackToolUsage(
|
|
internalName,
|
|
false,
|
|
duration,
|
|
errorMessage.length,
|
|
errorType,
|
|
errorMessage,
|
|
);
|
|
|
|
// Run PostToolUse hooks for error case - exit 2 injects stderr
|
|
let postToolUseFeedback: string[] = [];
|
|
try {
|
|
const postHookResult = await runPostToolUseHooks(
|
|
internalName,
|
|
args as Record<string, unknown>,
|
|
{ status: "error", output: errorMessage },
|
|
options?.toolCallId,
|
|
undefined, // workingDirectory
|
|
undefined, // agentId
|
|
undefined, // precedingReasoning - not available in tool manager context
|
|
undefined, // precedingAssistantMessage - not available in tool manager context
|
|
);
|
|
postToolUseFeedback = postHookResult.feedback;
|
|
} catch {
|
|
// Silently ignore hook errors
|
|
}
|
|
|
|
// Run PostToolUseFailure hooks - exit 2 injects stderr
|
|
let postToolUseFailureFeedback: string[] = [];
|
|
try {
|
|
const failureHookResult = await runPostToolUseFailureHooks(
|
|
internalName,
|
|
args as Record<string, unknown>,
|
|
errorMessage,
|
|
errorType,
|
|
options?.toolCallId,
|
|
undefined, // workingDirectory
|
|
undefined, // agentId
|
|
undefined, // precedingReasoning - not available in tool manager context
|
|
undefined, // precedingAssistantMessage - not available in tool manager context
|
|
);
|
|
postToolUseFailureFeedback = failureHookResult.feedback;
|
|
} catch {
|
|
// Silently ignore hook execution errors
|
|
}
|
|
|
|
// Combine feedback from both hook types
|
|
const allFeedback = [...postToolUseFeedback, ...postToolUseFailureFeedback];
|
|
const finalErrorMessage =
|
|
allFeedback.length > 0
|
|
? `${errorMessage}\n\n[Hook feedback]:\n${allFeedback.join("\n")}`
|
|
: errorMessage;
|
|
|
|
// Don't console.error here - it pollutes the TUI
|
|
// The error message is already returned in toolReturn
|
|
return {
|
|
toolReturn: finalErrorMessage,
|
|
status: "error",
|
|
};
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Gets all loaded tool names (for passing to Letta agent creation).
|
|
*
|
|
* @returns Array of tool names
|
|
*/
|
|
export function getToolNames(): string[] {
|
|
return Array.from(toolRegistry.keys());
|
|
}
|
|
|
|
/**
|
|
* Returns all Letta Code tool names known to this build, regardless of what is currently loaded.
|
|
* Useful for unlinking/removing tools when switching providers/models.
|
|
*/
|
|
export function getAllLettaToolNames(): string[] {
|
|
return [...TOOL_NAMES];
|
|
}
|
|
|
|
/**
|
|
* Gets all loaded tool schemas (for inspection/debugging).
|
|
*
|
|
* @returns Array of tool schemas
|
|
*/
|
|
export function getToolSchemas(): ToolSchema[] {
|
|
return Array.from(toolRegistry.values()).map((tool) => tool.schema);
|
|
}
|
|
|
|
/**
|
|
* Gets a single tool's schema by name.
|
|
*
|
|
* @param name - The tool name
|
|
* @returns The tool schema or undefined if not found
|
|
*/
|
|
export function getToolSchema(name: string): ToolSchema | undefined {
|
|
const internalName = resolveInternalToolName(name);
|
|
if (!internalName) return undefined;
|
|
return toolRegistry.get(internalName)?.schema;
|
|
}
|
|
|
|
/**
|
|
* Clears the tool registry (useful for testing).
|
|
*/
|
|
export function clearTools(): void {
|
|
toolRegistry.clear();
|
|
}
|
|
|
|
/**
|
|
* Clears the tool registry with lock protection.
|
|
* Acquires the switch lock, clears the registry, then releases the lock.
|
|
* This ensures sendMessageStream() waits for the clear to complete.
|
|
*/
|
|
export function clearToolsWithLock(): void {
|
|
acquireSwitchLock();
|
|
try {
|
|
toolRegistry.clear();
|
|
} finally {
|
|
releaseSwitchLock();
|
|
}
|
|
}
|