@frontmcp/sdk 0.6.3 → 0.7.1

package/agent/agent-execution-loop.d.ts

@@ -0,0 +1,209 @@
+import { AgentLlmAdapter, AgentMessage, AgentToolDefinition, AgentToolCall, AgentCompletionOptions, FrontMcpLogger } from '../common';
+/**
+ * Configuration for the agent execution loop.
+ */
+export interface AgentExecutionLoopConfig {
+    /**
+     * LLM adapter for making completions.
+     */
+    adapter: AgentLlmAdapter;
+    /**
+     * System instructions for the agent.
+     */
+    systemInstructions: string;
+    /**
+     * Available tools for the agent to use.
+     */
+    tools: AgentToolDefinition[];
+    /**
+     * Maximum number of iterations (tool call rounds).
+     * @default 10
+     */
+    maxIterations?: number;
+    /**
+     * Timeout for the entire execution in milliseconds.
+     * @default 120000 (2 minutes)
+     */
+    timeout?: number;
+    /**
+     * Completion options (temperature, maxTokens, etc.).
+     */
+    completionOptions?: AgentCompletionOptions;
+    /**
+     * Logger for debugging.
+     */
+    logger?: FrontMcpLogger;
+    /**
+     * Callback when a tool call is made.
+     */
+    onToolCall?: (toolCall: AgentToolCall) => void;
+    /**
+     * Callback when a tool result is received.
+     */
+    onToolResult?: (toolCall: AgentToolCall, result: unknown, error?: Error) => void;
+    /**
+     * Callback for streaming content.
+     */
+    onContent?: (content: string) => void;
+    /**
+     * Callback for each iteration.
+     */
+    onIteration?: (iteration: number, message: AgentMessage) => void;
+    /**
+     * Callback when LLM request starts.
+     */
+    onLlmStart?: (iteration: number, maxIterations: number) => void;
+    /**
+     * Callback when LLM response is received (with usage stats).
+     */
+    onLlmComplete?: (iteration: number, usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    }) => void;
+    /**
+     * Callback when tool calls are extracted from LLM response.
+     */
+    onToolsIdentified?: (count: number, names: string[]) => void;
+    /**
+     * Callback before a tool starts execution.
+     */
+    onToolStart?: (toolCall: AgentToolCall, index: number, total: number) => void;
+    /**
+     * Callback when agent execution is complete.
+     */
+    onComplete?: (content: string | null, error?: Error) => void;
+}
+/**
+ * Result of an agent execution.
+ */
+export interface AgentExecutionResult {
+    /**
+     * Final response content from the agent.
+     */
+    content: string | null;
+    /**
+     * All messages in the conversation.
+     */
+    messages: AgentMessage[];
+    /**
+     * Number of iterations (tool call rounds) performed.
+     */
+    iterations: number;
+    /**
+     * Total token usage.
+     */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens?: number;
+    };
+    /**
+     * Whether the execution completed successfully.
+     */
+    success: boolean;
+    /**
+     * Error if execution failed.
+     */
+    error?: Error;
+    /**
+     * Duration in milliseconds.
+     */
+    durationMs: number;
+}
+/**
+ * Handler function for executing tools.
+ */
+export type ToolExecutor = (name: string, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Agent execution loop for processing LLM interactions.
+ *
+ * The loop:
+ * 1. Sends the current prompt to the LLM
+ * 2. Processes tool calls if any
+ * 3. Adds tool results to the conversation
+ * 4. Repeats until the LLM responds with text or max iterations
+ *
+ * @example
+ * ```typescript
+ * const loop = new AgentExecutionLoop({
+ *   adapter: myLlmAdapter,
+ *   systemInstructions: 'You are a helpful assistant.',
+ *   tools: [searchTool, calculateTool],
+ * });
+ *
+ * const result = await loop.run(
+ *   'What is the weather in Paris?',
+ *   async (name, args) => {
+ *     // Execute the tool and return result
+ *     return toolRegistry.execute(name, args);
+ *   },
+ * );
+ *
+ * console.log(result.content);
+ * ```
+ */
+export declare class AgentExecutionLoop {
+    private readonly config;
+    constructor(config: AgentExecutionLoopConfig);
+    /**
+     * Run the execution loop with a user message.
+     *
+     * @param userMessage - The user's input message
+     * @param toolExecutor - Function to execute tools
+     * @param existingMessages - Optional existing conversation history
+     * @returns Execution result
+     */
+    run(userMessage: string, toolExecutor: ToolExecutor, existingMessages?: AgentMessage[]): Promise<AgentExecutionResult>;
+    /**
+     * Run the execution loop with streaming.
+     *
+     * @param userMessage - The user's input message
+     * @param toolExecutor - Function to execute tools
+     * @param existingMessages - Optional existing conversation history
+     * @returns AsyncGenerator yielding chunks and final result
+     */
+    runStreaming(userMessage: string, toolExecutor: ToolExecutor, existingMessages?: AgentMessage[]): AsyncGenerator<AgentStreamEvent>;
+    private executeLoop;
+    private executeLoopStreaming;
+}
+/**
+ * Events emitted during streaming execution.
+ */
+export type AgentStreamEvent = {
+    type: 'iteration';
+    iteration: number;
+} | {
+    type: 'content';
+    content: string;
+} | {
+    type: 'tool_call';
+    toolCall: Partial<AgentToolCall> & {
+        id: string;
+    };
+} | {
+    type: 'tool_start';
+    toolCall: AgentToolCall;
+} | {
+    type: 'tool_end';
+    toolCall: AgentToolCall;
+    result: unknown;
+    error?: Error;
+} | {
+    type: 'usage';
+    promptTokens: number;
+    completionTokens: number;
+} | {
+    type: 'error';
+    error: Error;
+} | {
+    type: 'done';
+    result: AgentExecutionResult;
+};
+/**
+ * Error thrown when agent reaches maximum iterations.
+ */
+export declare class AgentMaxIterationsError extends Error {
+    readonly maxIterations: number;
+    constructor(message: string, maxIterations: number);
+}
+//# sourceMappingURL=agent-execution-loop.d.ts.map

package/agent/agent-execution-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution-loop.d.ts","sourceRoot":"","sources":["../../src/agent/agent-execution-loop.ts"],"names":[],"mappings":"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"}

package/agent/agent.events.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Agent change event types and emitter.
+ */
+import type { AgentInstance } from './agent.instance';
+/**
+ * Types of changes that can occur in the agent registry.
+ */
+export type AgentChangeKind = 'added' | 'removed' | 'updated' | 'reset' | 'execution_start' | 'execution_complete' | 'execution_error';
+/**
+ * Scope of the change event.
+ */
+export type AgentChangeScope = 'global' | 'scope' | 'app' | 'plugin' | 'agent';
+/**
+ * Event emitted when agents change.
+ */
+export interface AgentChangeEvent {
+    /**
+     * Type of change.
+     */
+    kind: AgentChangeKind;
+    /**
+     * Scope where the change occurred.
+     */
+    changeScope: AgentChangeScope;
+    /**
+     * Registry version number.
+     */
+    version: number;
+    /**
+     * Snapshot of all agents after the change.
+     */
+    snapshot: readonly AgentInstance[];
+    /**
+     * ID of the affected agent (for single-agent events).
+     */
+    agentId?: string;
+    /**
+     * Full name of the agent (including parent path).
+     */
+    agentFullName?: string;
+    /**
+     * Owner reference (app, plugin, or parent agent).
+     */
+    owner?: {
+        kind: AgentChangeScope;
+        id: string;
+    };
+    /**
+     * Timestamp of the event.
+     */
+    timestamp?: number;
+    /**
+     * Additional metadata for execution events.
+     */
+    execution?: {
+        /** Run ID for this execution */
+        runId: string;
+        /** Input provided to the agent */
+        input?: unknown;
+        /** Output from the agent (for completion events) */
+        output?: unknown;
+        /** Error if execution failed */
+        error?: Error;
+        /** Duration in milliseconds */
+        durationMs?: number;
+    };
+}
+/**
+ * Listener function type.
+ */
+export type AgentChangeListener = (event: AgentChangeEvent) => void;
+/**
+ * Unsubscribe function type.
+ */
+export type Unsubscribe = () => void;
+/**
+ * Event emitter for agent changes.
+ *
+ * Allows components to subscribe to agent lifecycle events.
+ */
+export declare class AgentEmitter {
+    private listeners;
+    /**
+     * Subscribe to agent change events (alias for subscribe).
+     *
+     * @param listener Function to call when events occur
+     * @returns Unsubscribe function
+     */
+    on(listener: AgentChangeListener): Unsubscribe;
+    /**
+     * Subscribe to agent change events.
+     *
+     * @param listener Function to call when events occur
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: AgentChangeListener): Unsubscribe;
+    /**
+     * Emit an event to all listeners.
+     */
+    emit(event: AgentChangeEvent): void;
+    /**
+     * Remove all listeners.
+     */
+    clear(): void;
+    /**
+     * Get the number of listeners.
+     */
+    get size(): number;
+    /**
+     * Emit an agent added event.
+     */
+    emitAdded(agentId: string, agentFullName: string, owner: {
+        kind: AgentChangeScope;
+        id: string;
+    }, version: number, snapshot: readonly AgentInstance[]): void;
+    /**
+     * Emit an agent removed event.
+     */
+    emitRemoved(agentId: string, agentFullName: string, owner: {
+        kind: AgentChangeScope;
+        id: string;
+    }, version: number, snapshot: readonly AgentInstance[]): void;
+    /**
+     * Emit an execution start event.
+     */
+    emitExecutionStart(agentId: string, agentFullName: string, owner: {
+        kind: AgentChangeScope;
+        id: string;
+    }, runId: string, version: number, snapshot: readonly AgentInstance[], input?: unknown): void;
+    /**
+     * Emit an execution complete event.
+     */
+    emitExecutionComplete(agentId: string, agentFullName: string, owner: {
+        kind: AgentChangeScope;
+        id: string;
+    }, runId: string, output: unknown, durationMs: number, version: number, snapshot: readonly AgentInstance[]): void;
+    /**
+     * Emit an execution error event.
+     */
+    emitExecutionError(agentId: string, agentFullName: string, owner: {
+        kind: AgentChangeScope;
+        id: string;
+    }, runId: string, error: Error, durationMs: number, version: number, snapshot: readonly AgentInstance[]): void;
+}
+/**
+ * Global agent emitter instance.
+ */
+export declare const agentEmitter: AgentEmitter;
+//# sourceMappingURL=agent.events.d.ts.map

package/agent/agent.events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.events.d.ts","sourceRoot":"","sources":["../../src/agent/agent.events.ts"],"names":[],"mappings":"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"}

package/agent/agent.instance.d.ts

@@ -0,0 +1,201 @@
+import { EntryOwnerRef, AgentCallArgs, AgentCallExtra, AgentContext, AgentEntry, AgentRecord, ParsedAgentResult, SafeTransformResult, ToolInputType, ToolOutputType, AgentInputOf, AgentOutputOf, AgentLlmAdapter } from '../common';
+import { ToolInstance } from '../tool/tool.instance';
+import ProviderRegistry from '../provider/provider.registry';
+import HookRegistry from '../hooks/hook.registry';
+import { Scope } from '../scope';
+import type { CallToolRequest, Tool } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Concrete implementation of AgentEntry.
+ *
+ * AgentInstance manages an agent's lifecycle, including:
+ * - LLM adapter initialization and configuration
+ * - Agent-scoped tool registration (tools are private to this agent)
+ * - Hook registration for agent-specific flows
+ * - Input/output schema parsing and validation
+ * - Tool definition generation for MCP exposure
+ * - Swarm visibility configuration
+ *
+ * @template InSchema - Zod schema type for agent input
+ * @template OutSchema - Zod schema type for agent output
+ * @template In - Inferred input type from InSchema
+ * @template Out - Inferred output type from OutSchema
+ *
+ * @example
+ * ```typescript
+ * // Created internally by AgentRegistry
+ * const instance = new AgentInstance(record, providers, owner);
+ * await instance.ready;
+ *
+ * // Create an execution context
+ * const context = instance.create(input, { authInfo });
+ * const result = await context.execute(input);
+ * ```
+ */
+export declare class AgentInstance<InSchema extends ToolInputType = ToolInputType, OutSchema extends ToolOutputType = ToolOutputType, In = AgentInputOf<{
+    inputSchema: InSchema;
+}>, Out = AgentOutputOf<{
+    outputSchema: OutSchema;
+}>> extends AgentEntry<InSchema, OutSchema, In, Out> {
+    private readonly providers;
+    readonly scope: Scope;
+    readonly hooks: HookRegistry;
+    /** The LLM adapter for this agent */
+    private llmAdapter;
+    /** Agent-scoped tools (from @Agent({ tools: [...] })) */
+    private agentTools;
+    /** Agent's private scope (like a private app with its own registries) */
+    private agentScope;
+    /**
+     * The agent exposed as a standard tool for registration in parent scope.
+     * This allows the agent to be called like any other tool (use-agent:*) and
+     * go through the standard tools:call-tool flow with all plugins/hooks.
+     */
+    private agentToolInstance;
+    constructor(record: AgentRecord, providers: ProviderRegistry, owner: EntryOwnerRef);
+    protected initialize(): Promise<void>;
+    /**
+     * Initialize the agent's private scope.
+     *
+     * The AgentScope acts as a "private app" with its own registries for:
+     * - Tools (from @Agent({ tools: [...] }))
+     * - Plugins (from @Agent({ plugins: [...] }))
+     * - Adapters (from @Agent({ adapters: [...] }))
+     * - Providers (from @Agent({ providers: [...] }))
+     * - Resources, Prompts, nested Agents
+     *
+     * This scope is isolated from the parent scope and not exposed externally.
+     * Tool calls are routed through the scope's call-tool flow for full lifecycle support.
+     */
+    private initializeAgentTools;
+    /**
+     * Initialize the LLM adapter from the agent's metadata configuration.
+     */
+    private initializeLlmAdapter;
+    /**
+     * Register hooks from the agent class.
+     * Validates that hooks are only registered for agent-specific flows.
+     *
+     * @throws InvalidHookFlowError If hooks are registered for non-agent flows
+     */
+    private registerHooks;
+    /**
+     * Get the class name from the record's provide property.
+     * Used for error messages and logging.
+     */
+    private getClassName;
+    /**
+     * Create the agent as a standard ToolInstance for registration in parent scope.
+     *
+     * This follows the same pattern as OpenAPI adapters that create dynamic tools
+     * with a prebuilt execute function. The agent's execute handler internally calls
+     * the agent's LLM execution loop.
+     *
+     * Benefits:
+     * - Agent tools go through standard tools:call-tool flow
+     * - Plugin metadata extensions (cache, codecall) work on agents
+     * - CodeCall can discover and search for agent tools
+     * - Unified hook/plugin execution
+     */
+    private createAgentAsTool;
+    /**
+     * Build ToolMetadata from AgentMetadata.
+     *
+     * Includes plugin metadata extensions (cache, codecall) from agent metadata
+     * so plugins can apply to agent tools.
+     */
+    private buildAgentToolMetadata;
+    /**
+     * Create the execute handler for the agent tool.
+     *
+     * This handler is called when the tool is invoked through the standard
+     * tools:call-tool flow. It creates an AgentContext and runs the LLM loop.
+     */
+    private createAgentToolExecuteHandler;
+    /**
+     * Get the ToolInstance representing this agent.
+     *
+     * This is used by AgentRegistry to register the agent tool in the parent
+     * scope's ToolRegistry, enabling standard tool flow with plugins/hooks.
+     *
+     * @returns The agent's ToolInstance, or null if not created
+     */
+    getToolInstance(): ToolInstance | null;
+    getMetadata(): import("../common").AgentMetadata<ToolInputType, ToolOutputType>;
+    getOutputSchema(): OutSchema | undefined;
+    /**
+     * Get the LLM adapter for this agent.
+     */
+    getLlmAdapter(): AgentLlmAdapter | null;
+    /**
+     * Create an AgentContext instance for executing this agent.
+     *
+     * @param input - The input arguments for the agent
+     * @param ctx - Extra context including authInfo
+     * @returns A new AgentContext instance ready for execution
+     * @throws AgentNotConfiguredError If no LLM adapter is configured
+     */
+    create(input: AgentCallArgs, ctx: AgentCallExtra): AgentContext<InSchema, OutSchema, In, Out>;
+    /**
+     * Build the constructor arguments for creating an AgentContext.
+     *
+     * @param input - The input arguments for the agent
+     * @param ctx - Extra context including authInfo
+     * @param llmAdapter - The LLM adapter (passed explicitly to avoid non-null assertion)
+     */
+    private buildAgentCtorArgs;
+    /**
+     * Get tool definitions available to this agent.
+     * Returns only the agent's own tools (from @Agent({ tools: [...] })).
+     */
+    private getToolDefinitions;
+    /**
+     * Create a tool executor for agent-scoped tools.
+     *
+     * When `execution.useToolFlow` is enabled (default: true), tool calls are routed
+     * through the agent's private scope's call-tool flow. This enables full lifecycle
+     * support including:
+     * - Plugin integration (cache, PII, rate limiting, etc.)
+     * - Hook execution (will/did/around stages)
+     * - Authorization checks
+     * - UI rendering
+     * - MCP-compliant error handling
+     *
+     * When `execution.useToolFlow` is false, tools are executed directly for
+     * performance-critical scenarios.
+     *
+     * @param ctx - Extra context including authInfo
+     * @returns A function that executes tools by name
+     */
+    private createToolExecutor;
+    /**
+     * Extract the actual result from MCP CallToolResult format.
+     *
+     * The call-tool flow returns a CallToolResult with:
+     * - structuredContent: The raw tool output (preferred)
+     * - content: Array of text/image content (fallback)
+     * - isError: Whether the tool execution failed
+     *
+     * @param mcpResult - The CallToolResult from the flow
+     * @returns The extracted tool result
+     * @throws Error if the tool execution failed
+     */
+    private extractToolResult;
+    parseInput(input: CallToolRequest['params']): AgentCallArgs;
+    parseOutput(raw: Out | Partial<Out> | unknown): ParsedAgentResult;
+    safeParseOutput(raw: Out | Partial<Out> | unknown): SafeTransformResult<ParsedAgentResult>;
+    /**
+     * Get the MCP Tool definition for this agent.
+     * This allows the agent to be invoked as a tool by other agents or clients.
+     *
+     * @returns Tool definition with name, description, and input schema
+     */
+    getToolDefinition(): Tool;
+    /**
+     * Build the tool description from metadata.
+     */
+    private buildToolDescription;
+    isVisibleToSwarm(): boolean;
+    canSeeSwarm(): boolean;
+    getVisibleAgentIds(): string[];
+}
+//# sourceMappingURL=agent.instance.d.ts.map

package/agent/agent.instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.instance.d.ts","sourceRoot":"","sources":["../../src/agent/agent.instance.ts"],"names":[],"mappings":"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"}