@flink-app/flink 1.0.0 → 2.0.0-alpha.48

package/spec/SubAgentSupport.spec.ts

@@ -0,0 +1,941 @@
+import { FlinkAgent } from "../src/ai/FlinkAgent";
+import { LLMAdapter } from "../src/ai/LLMAdapter";
+import { SubAgentExecutor } from "../src/ai/SubAgentExecutor";
+import { FlinkContext } from "../src/FlinkContext";
+import { createStreamingMock } from "./testHelpers";
+
+describe("Sub-Agent Support", () => {
+    let mockCtx: FlinkContext;
+    let mockLLMAdapter: LLMAdapter;
+
+    beforeEach(() => {
+        mockCtx = {
+            repos: {},
+            plugins: {},
+            agents: {},
+        };
+
+        // Mock LLM Adapter
+        mockLLMAdapter = createStreamingMock([
+            {
+                textContent: "Test response",
+                toolCalls: [],
+                usage: { inputTokens: 10, outputTokens: 20 },
+                stopReason: "end_turn" as const,
+            },
+        ]);
+    });
+
+    describe("SubAgentExecutor", () => {
+        it("should create sub-agent executor with correct properties", () => {
+            const executor = new SubAgentExecutor("carAgent", mockCtx);
+
+            expect(executor.getSubAgentId()).toBe("car-agent");
+            expect(executor.isSubAgentExecutor()).toBe(true);
+        });
+
+        it("should generate correct tool schema", () => {
+            // Create a mock sub-agent
+            class CarAgent extends FlinkAgent<FlinkContext> {
+                description = "Expert in cars";
+                instructions = "You know about cars";
+                tools: string[] = [];
+            }
+
+            const carAgent = new CarAgent();
+            (mockCtx as any).agents = { carAgent };
+
+            const executor = new SubAgentExecutor("carAgent", mockCtx);
+            const schema = executor.getToolSchema();
+
+            expect(schema.name).toBe("ask_car_agent");
+            expect(schema.description).toContain("car-agent");
+            expect(schema.description).toContain("Expert in cars");
+            expect(schema.input_schema).toBeDefined();
+            expect(schema.input_schema.properties.query).toBeDefined();
+        });
+
+        it("should run sub-agent successfully", async () => {
+            // Create mock sub-agent
+            class SpecialistAgent extends FlinkAgent<FlinkContext> {
+                description = "Specialist";
+                instructions = "You are a specialist";
+                tools: string[] = [];
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+
+                async answerQuestion(query: string) {
+                    const response = this.run({ message: query });
+                    return await response.result;
+                }
+            }
+
+            const specialist = new SpecialistAgent();
+            specialist.setContext(mockCtx);
+            specialist.__init(new Map([["default", mockLLMAdapter]]), {});
+            (mockCtx as any).agents = { specialistAgent: specialist };
+
+            const executor = new SubAgentExecutor("specialistAgent", mockCtx);
+
+            const result = await executor.execute({
+                query: "What is the answer?",
+            });
+
+            expect(result.success).toBe(true);
+            if (result.success) {
+                expect(result.data.message).toBe("Test response");
+                expect(result.data.stepsUsed).toBeGreaterThan(0);
+            }
+        });
+
+        it("should handle missing sub-agent gracefully", async () => {
+            (mockCtx as any).agents = {};
+
+            const executor = new SubAgentExecutor("missingAgent", mockCtx);
+
+            const result = await executor.execute({ query: "test" });
+
+            expect(result.success).toBe(false);
+            if (!result.success) {
+                expect(result.error).toContain("not found");
+                expect(result.code).toBe("AGENT_NOT_FOUND");
+            }
+        });
+
+        it("should propagate user context to sub-agent", async () => {
+            // Create sub-agent with permissions
+            class AdminAgent extends FlinkAgent<FlinkContext> {
+                description = "Admin-only agent";
+                instructions = "You handle admin tasks";
+                tools: string[] = [];
+                permissions = "admin";
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            const adminAgent = new AdminAgent();
+            adminAgent.setContext(mockCtx);
+            adminAgent.__init(new Map([["default", mockLLMAdapter]]), {});
+            (mockCtx as any).agents = { adminAgent };
+
+            const executor = new SubAgentExecutor("adminAgent", mockCtx);
+
+            // Without permissions - should fail
+            const resultNoPerms = await executor.execute({ query: "test" }, { permissions: [] });
+            expect(resultNoPerms.success).toBe(false);
+
+            // With permissions - should succeed
+            const resultWithPerms = await executor.execute({ query: "test" }, { permissions: ["admin"] });
+            expect(resultWithPerms.success).toBe(true);
+        });
+
+        it("should format sub-agent result for AI", () => {
+            const executor = new SubAgentExecutor("testAgent", mockCtx);
+
+            const successResult = {
+                success: true as const,
+                data: {
+                    message: "The answer is 42",
+                    toolCalls: [],
+                    stepsUsed: 2,
+                    usage: { inputTokens: 50, outputTokens: 30 },
+                    stoppedEarly: false,
+                },
+            };
+
+            const formatted = executor.formatResultForAI(successResult);
+            const parsed = JSON.parse(formatted);
+
+            expect(parsed.answer).toBe("The answer is 42");
+            expect(parsed.stepsUsed).toBe(2);
+            expect(parsed.tokensUsed).toBe(80);
+        });
+    });
+
+    describe("Agent with sub-agents", () => {
+        it("should support agents property with class references", () => {
+            class CarAgent extends FlinkAgent<FlinkContext> {
+                description = "Car expert";
+                instructions = "You know about cars";
+                tools: string[] = [];
+            }
+
+            class UserAgent extends FlinkAgent<FlinkContext> {
+                description = "User expert";
+                instructions = "You know about users";
+                tools: string[] = [];
+            }
+
+            class OrchestratorAgent extends FlinkAgent<FlinkContext> {
+                description = "Orchestrator";
+                instructions = "You coordinate specialists";
+                tools: string[] = [];
+                agents = [CarAgent, UserAgent]; // ✅ Class references!
+            }
+
+            const orchestrator = new OrchestratorAgent();
+
+            expect(orchestrator.agents).toEqual([CarAgent, UserAgent]);
+        });
+
+        it("should support agents property with strings (backwards compatibility)", () => {
+            class OrchestratorAgent extends FlinkAgent<FlinkContext> {
+                description = "Orchestrator";
+                instructions = "You coordinate specialists";
+                tools: string[] = [];
+                agents = ["car-agent", "user-agent"]; // ✅ Still works!
+            }
+
+            const orchestrator = new OrchestratorAgent();
+
+            expect(orchestrator.agents).toEqual(["car-agent", "user-agent"]);
+        });
+
+        it("should support mixed class and string references", () => {
+            class LocalAgent extends FlinkAgent<FlinkContext> {
+                description = "Local agent";
+                instructions = "Local";
+                tools: string[] = [];
+            }
+
+            class OrchestratorAgent extends FlinkAgent<FlinkContext> {
+                description = "Orchestrator";
+                instructions = "You coordinate specialists";
+                tools: string[] = [];
+                agents = [LocalAgent, "external-agent"]; // ✅ Mix both!
+            }
+
+            const orchestrator = new OrchestratorAgent();
+
+            expect(orchestrator.agents).toEqual([LocalAgent, "external-agent"]);
+        });
+
+        it("should run orchestrator with sub-agent delegation", async () => {
+            // Create specialist agent
+            class SpecialistAgent extends FlinkAgent<FlinkContext> {
+                description = "Specialist";
+                instructions = "You are a specialist";
+                tools: string[] = [];
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            // Create orchestrator agent
+            class OrchestratorAgent extends FlinkAgent<FlinkContext> {
+                description = "Orchestrator";
+                instructions = "You delegate to specialists";
+                tools: string[] = [];
+                agents = [SpecialistAgent]; // ✅ Using class reference!
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+
+                async handleQuery(query: string) {
+                    const response = this.run({ message: query });
+                    return await response.result;
+                }
+            }
+
+            const specialist = new SpecialistAgent();
+            specialist.setContext(mockCtx);
+            // Initialize specialist with its own LLM adapter
+            specialist.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            const orchestrator = new OrchestratorAgent();
+            orchestrator.setContext(mockCtx);
+
+            (mockCtx as any).agents = {
+                specialistAgent: specialist,
+                orchestratorAgent: orchestrator,
+            };
+
+            // Create sub-agent executor
+            const subAgentExecutor = new SubAgentExecutor("specialistAgent", mockCtx);
+
+            // Setup tools and LLM
+            const toolsMap = new Map([["ask_specialist_agent", subAgentExecutor as any]]);
+
+            // Mock LLM to delegate to specialist
+            const orchestratorMockAdapter = createStreamingMock([
+                // First: orchestrator decides to delegate
+                {
+                    textContent: "I'll ask the specialist",
+                    toolCalls: [
+                        {
+                            id: "1",
+                            name: "ask_specialist_agent",
+                            input: { query: "What is the answer?" },
+                        },
+                    ],
+                    usage: { inputTokens: 50, outputTokens: 30 },
+                    stopReason: "tool_use" as const,
+                },
+                // Second: specialist responds
+                {
+                    textContent: "The specialist says 42",
+                    toolCalls: [],
+                    usage: { inputTokens: 30, outputTokens: 20 },
+                    stopReason: "end_turn" as const,
+                },
+                // Third: orchestrator synthesizes
+                {
+                    textContent: "Based on specialist: 42",
+                    toolCalls: [],
+                    usage: { inputTokens: 20, outputTokens: 15 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            orchestrator.__init(new Map([["default", orchestratorMockAdapter]]), Object.fromEntries(toolsMap));
+
+            const result = await orchestrator.handleQuery("What is the answer?");
+
+            expect(result.message).toContain("42");
+            expect(result.toolCalls.length).toBeGreaterThan(0);
+
+            // Check that sub-agent call is marked
+            const subAgentCall = result.toolCalls.find((tc) => tc.isAgentCall);
+            expect(subAgentCall).toBeDefined();
+            expect(subAgentCall?.agentId).toBe("specialist-agent");
+
+            // Check sub-agent calls tracking
+            expect(result.subAgentCalls).toBeDefined();
+            expect(result.subAgentCalls?.length).toBeGreaterThan(0);
+            expect(result.subAgentCalls?.[0].agentId).toBe("specialist-agent");
+
+            // Token usage should be aggregated
+            expect(result.usage?.inputTokens).toBeGreaterThan(50);
+            expect(result.usage?.outputTokens).toBeGreaterThan(30);
+        });
+
+        it("should stream sub-agent events", async () => {
+            // Setup similar to previous test
+            class SpecialistAgent extends FlinkAgent<FlinkContext> {
+                description = "Specialist";
+                instructions = "You are a specialist";
+                tools: string[] = [];
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            class OrchestratorAgent extends FlinkAgent<FlinkContext> {
+                description = "Orchestrator";
+                instructions = "You delegate";
+                tools: string[] = [];
+                agents = [SpecialistAgent]; // ✅ Using class reference!
+
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            // Create specialist with its own mock (simulates specialist answering)
+            const specialistMock = createStreamingMock([
+                {
+                    textContent: "Answer from specialist",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            const specialist = new SpecialistAgent();
+            specialist.setContext(mockCtx);
+            specialist.__init(new Map([["default", specialistMock]]), {});
+
+            const orchestrator = new OrchestratorAgent();
+            orchestrator.setContext(mockCtx);
+
+            (mockCtx as any).agents = {
+                specialistAgent: specialist,
+                orchestratorAgent: orchestrator,
+            };
+
+            const subAgentExecutor = new SubAgentExecutor("specialistAgent", mockCtx);
+
+            const toolsMap = new Map([["ask_specialist_agent", subAgentExecutor as any]]);
+
+            // Orchestrator mock that delegates to specialist
+            const orchestratorMock = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "1",
+                            name: "ask_specialist_agent",
+                            input: { query: "test" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "tool_use" as const,
+                },
+                {
+                    textContent: "Final answer from orchestrator",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            orchestrator.__init(new Map([["default", orchestratorMock]]), Object.fromEntries(toolsMap));
+
+            const response = orchestrator.run({ message: "test" });
+
+            const events: any[] = [];
+            for await (const chunk of response.fullStream) {
+                events.push(chunk);
+            }
+
+            // Should have agent_call_start and agent_call_result events
+            const startEvent = events.find((e) => e.type === "agent_call_start");
+            const resultEvent = events.find((e) => e.type === "agent_call_result");
+
+            expect(startEvent).toBeDefined();
+            expect(startEvent?.agentId).toBe("specialist-agent");
+            expect(startEvent?.input).toEqual({ query: "test" });
+
+            expect(resultEvent).toBeDefined();
+            expect(resultEvent?.agentId).toBe("specialist-agent");
+            expect(resultEvent?.result.message).toBe("Answer from specialist");
+
+            // Should also have text_delta events
+            const textEvents = events.filter((e) => e.type === "text_delta");
+            expect(textEvents.length).toBeGreaterThan(0);
+
+            // Should have complete event at the end
+            const completeEvent = events.find((e) => e.type === "complete");
+            expect(completeEvent).toBeDefined();
+            expect(completeEvent?.result.message).toBe("Final answer from orchestrator");
+        });
+
+        it("should handle multiple parallel sub-agent calls", async () => {
+            // Create two specialist agents
+            class CarAgent extends FlinkAgent<FlinkContext> {
+                description = "Car expert";
+                instructions = "You know about cars";
+                tools: string[] = [];
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            class UserAgent extends FlinkAgent<FlinkContext> {
+                description = "User expert";
+                instructions = "You know about users";
+                tools: string[] = [];
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            class OrchestratorAgent extends FlinkAgent<FlinkContext> {
+                description = "Orchestrator";
+                instructions = "You coordinate";
+                tools: string[] = [];
+                agents = [CarAgent, UserAgent]; // ✅ Using class references!
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            const carAgent = new CarAgent();
+            carAgent.setContext(mockCtx);
+            // Initialize car agent with its own LLM adapter
+            carAgent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            const userAgent = new UserAgent();
+            userAgent.setContext(mockCtx);
+            // Initialize user agent with its own LLM adapter
+            userAgent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            const orchestrator = new OrchestratorAgent();
+            orchestrator.setContext(mockCtx);
+
+            (mockCtx as any).agents = { carAgent, userAgent, orchestratorAgent: orchestrator };
+
+            const carExecutor = new SubAgentExecutor("carAgent", mockCtx);
+            const userExecutor = new SubAgentExecutor("userAgent", mockCtx);
+
+            const toolsMap = new Map([
+                ["ask_car_agent", carExecutor as any],
+                ["ask_user_agent", userExecutor as any],
+            ]);
+
+            // Mock LLM to call both agents in parallel (same turn)
+            const parallelMockAdapter = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        { id: "1", name: "ask_car_agent", input: { query: "cars?" } },
+                        { id: "2", name: "ask_user_agent", input: { query: "users?" } },
+                    ],
+                    usage: { inputTokens: 20, outputTokens: 10 },
+                    stopReason: "tool_use" as const,
+                },
+                // Car agent response
+                {
+                    textContent: "Cars are vehicles",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+                // User agent response
+                {
+                    textContent: "Users are people",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+                // Final synthesis
+                {
+                    textContent: "Cars and users combined",
+                    toolCalls: [],
+                    usage: { inputTokens: 15, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            orchestrator.__init(new Map([["default", parallelMockAdapter]]), Object.fromEntries(toolsMap));
+
+            const result = await orchestrator.run({ message: "test" }).result;
+
+            // Should have 2 sub-agent calls
+            expect(result.subAgentCalls?.length).toBe(2);
+
+            const carCall = result.subAgentCalls?.find((c) => c.agentId === "car-agent");
+            const userCall = result.subAgentCalls?.find((c) => c.agentId === "user-agent");
+
+            expect(carCall).toBeDefined();
+            expect(userCall).toBeDefined();
+
+            // Token usage should aggregate from both sub-agents
+            const totalTokens = (result.usage?.inputTokens || 0) + (result.usage?.outputTokens || 0);
+            expect(totalTokens).toBeGreaterThan(50); // Base + both agents
+        });
+    });
+
+    describe("Sub-agent permissions", () => {
+        it("should respect sub-agent permissions", async () => {
+            class RestrictedAgent extends FlinkAgent<FlinkContext> {
+                description = "Restricted";
+                instructions = "Admin only";
+                tools: string[] = [];
+                permissions = "admin";
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            class OrchestratorAgent extends FlinkAgent<FlinkContext> {
+                description = "Orchestrator";
+                instructions = "You delegate";
+                tools: string[] = [];
+                agents = [RestrictedAgent]; // ✅ Using class reference!
+                setContext(ctx: FlinkContext) {
+                    (this as any).ctx = ctx;
+                }
+            }
+
+            const restricted = new RestrictedAgent();
+            restricted.setContext(mockCtx);
+
+            const orchestrator = new OrchestratorAgent();
+            orchestrator.setContext(mockCtx);
+
+            (mockCtx as any).agents = { restrictedAgent: restricted };
+
+            const subAgentExecutor = new SubAgentExecutor("restrictedAgent", mockCtx);
+
+            const toolsMap = new Map([["ask_restricted_agent", subAgentExecutor as any]]);
+
+            const restrictedMockAdapter = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "1",
+                            name: "ask_restricted_agent",
+                            input: { query: "test" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "tool_use" as const,
+                },
+                {
+                    textContent: "Permission denied response",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            orchestrator.__init(new Map([["default", restrictedMockAdapter]]), Object.fromEntries(toolsMap));
+
+            // Execute without admin permission
+            const response = orchestrator.withUser({ permissions: [] }).run({ message: "test" });
+
+            const result = await response.result;
+
+            // Sub-agent call should have failed
+            const subAgentCall = result.toolCalls.find((tc) => tc.isAgentCall);
+            expect(subAgentCall?.error).toBeDefined();
+        });
+    });
+
+    describe("Recursion depth limiting", () => {
+        it("should throw error when depth exceeds limit", async () => {
+            // Create simple agent with depth limit
+            class TestAgent extends FlinkAgent<FlinkContext> {
+                id = "test-agent";
+                description = "Test agent";
+                instructions = "You are a test agent";
+                tools: string[] = [];
+                limits = { maxSubAgentDepth: 3 }; // Low limit for testing
+            }
+
+            const agent = new TestAgent();
+            agent.ctx = mockCtx;
+            agent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            // Execute with depth already at limit (simulating deep sub-agent call)
+            const response = agent.run({
+                message: "test",
+                metadata: {
+                    subAgentDepth: 4, // Already exceeds limit of 3
+                },
+            });
+
+            try {
+                await response.result;
+                fail("Should have thrown depth limit error");
+            } catch (err: any) {
+                expect(err.message).toContain("recursion depth limit exceeded");
+                expect(err.message).toContain("max: 3");
+                expect(err.message).toContain("current: 4");
+            }
+        });
+
+        it("should include delegation chain in depth limit error", async () => {
+            // Create agent with depth limit
+            class TestAgent extends FlinkAgent<FlinkContext> {
+                id = "test-agent";
+                description = "Test agent";
+                instructions = "You are a test agent";
+                tools: string[] = [];
+                limits = { maxSubAgentDepth: 3 };
+            }
+
+            const agent = new TestAgent();
+            agent.ctx = mockCtx;
+            agent.__init(new Map([["default", mockLLMAdapter]]), {});
+
+            // Simulate a delegation chain: orchestrator -> car-agent -> pricing-agent -> test-agent
+            const response = agent.run({
+                message: "test",
+                metadata: {
+                    subAgentDepth: 4, // Exceeds limit of 3
+                    parentAgentId: "pricing-agent",
+                    parentMetadata: {
+                        parentAgentId: "car-agent",
+                        parentMetadata: {
+                            parentAgentId: "orchestrator",
+                        },
+                    },
+                },
+            });
+
+            try {
+                await response.result;
+                fail("Should have thrown depth limit error");
+            } catch (err: any) {
+                expect(err.message).toContain("recursion depth limit exceeded");
+                expect(err.message).toContain("Delegation chain:");
+                expect(err.message).toContain("orchestrator");
+                expect(err.message).toContain("car-agent");
+                expect(err.message).toContain("pricing-agent");
+                expect(err.message).toContain("test-agent");
+            }
+        });
+
+        it("should respect custom maxSubAgentDepth limit", async () => {
+            // Create agents with declared dependencies
+            class AgentA extends FlinkAgent<FlinkContext> {
+                id = "agent-a";
+                description = "Agent A";
+                instructions = "You delegate to Agent B";
+                tools: string[] = [];
+                agents: any[] = []; // Will be populated after instantiation
+                limits = { maxSubAgentDepth: 2 }; // Custom limit
+            }
+
+            class AgentB extends FlinkAgent<FlinkContext> {
+                id = "agent-b";
+                description = "Agent B";
+                instructions = "You delegate to Agent A (creating circular delegation)";
+                tools: string[] = [];
+                agents: any[] = []; // Will be populated after instantiation
+                limits = { maxSubAgentDepth: 2 };
+            }
+
+            const agentA = new AgentA();
+            const agentB = new AgentB();
+
+            // Set up circular references after instantiation
+            agentA.agents = [AgentB];
+            agentB.agents = [AgentA];
+
+            agentA.ctx = mockCtx;
+            agentB.ctx = mockCtx;
+
+            // Each agent needs its own mock that always delegates back
+            // Agent A mock: always delegates to B (will be called multiple times)
+            const mockA = createStreamingMock([
+                // First call from root
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_1",
+                            name: "ask_agent_b",
+                            input: { query: "delegate" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "tool_use" as const,
+                },
+                // Second call (after B delegates back to A)
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_2",
+                            name: "ask_agent_b",
+                            input: { query: "delegate again" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "tool_use" as const,
+                },
+            ]);
+
+            // Agent B mock: always delegates to A
+            const mockB = createStreamingMock([
+                // First call from A
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_3",
+                            name: "ask_agent_a",
+                            input: { query: "delegate back" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "tool_use" as const,
+                },
+                // Second call
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_4",
+                            name: "ask_agent_a",
+                            input: { query: "delegate back again" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "tool_use" as const,
+                },
+            ]);
+
+            const toolsMapA = new Map([
+                ["ask_agent_b", new SubAgentExecutor("agentB", mockCtx)],
+            ]);
+            const toolsMapB = new Map([
+                ["ask_agent_a", new SubAgentExecutor("agentA", mockCtx)],
+            ]);
+
+            agentA.__init(new Map([["default", mockA]]), Object.fromEntries(toolsMapA) as any);
+            agentB.__init(new Map([["default", mockB]]), Object.fromEntries(toolsMapB) as any);
+
+            (mockCtx as any).agents = { agentA, agentB };
+
+            // Execute - should hit custom depth limit (2)
+            // A (depth 0) -> B (depth 1) -> A (depth 2) -> B (depth 3 - exceeds limit!)
+            const response = agentA.run({ message: "Start delegation" });
+
+            const result = await response.result;
+
+            // The depth limit error should be captured as a sub-agent tool error
+            // (not thrown as an exception, since sub-agent failures are graceful)
+            expect(result.toolCalls.length).toBeGreaterThan(0);
+
+            // Find the first sub-agent call (A -> B)
+            const firstBCall = result.toolCalls.find(tc => tc.isAgentCall && tc.agentId === "agent-b");
+            expect(firstBCall).toBeDefined();
+            expect(firstBCall?.error).toBeUndefined(); // First call should succeed
+
+            // B should have called A, and A should have tried to call B again (depth 3)
+            const bResult = firstBCall?.output as any;
+            expect(bResult.toolCalls).toBeDefined();
+
+            // Find A's call back to B within B's execution
+            const aCallsBack = bResult.toolCalls.find((tc: any) => tc.isAgentCall && tc.agentId === "agent-a");
+            expect(aCallsBack).toBeDefined();
+
+            // A's nested result should contain the depth limit error
+            const aNestedResult = aCallsBack.output as any;
+            const depthLimitError = aNestedResult?.toolCalls?.find((tc: any) =>
+                tc.error && tc.error.includes("recursion depth limit exceeded")
+            );
+
+            expect(depthLimitError).toBeDefined();
+            expect(depthLimitError?.error).toContain("max: 2");
+            expect(depthLimitError?.error).toContain("current: 3");
+            expect(depthLimitError?.error).toContain("Delegation chain");
+        });
+
+        it("should allow deep but finite delegation chains", async () => {
+            // Create a chain: A -> B -> C (depth 2, within default limit of 5)
+            // First declare all classes so they can reference each other
+            class AgentC extends FlinkAgent<FlinkContext> {
+                id = "agent-c";
+                description = "Agent C";
+                instructions = "You answer directly";
+                tools: string[] = [];
+            }
+
+            class AgentB extends FlinkAgent<FlinkContext> {
+                id = "agent-b";
+                description = "Agent B";
+                instructions = "You delegate to C";
+                tools: string[] = [];
+                agents = [AgentC]; // Declare dependency on C
+            }
+
+            class AgentA extends FlinkAgent<FlinkContext> {
+                id = "agent-a";
+                description = "Agent A";
+                instructions = "You delegate to B";
+                tools: string[] = [];
+                agents = [AgentB]; // Declare dependency on B
+            }
+
+            const agentA = new AgentA();
+            const agentB = new AgentB();
+            const agentC = new AgentC();
+
+            // A delegates to B
+            const mockA = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_1",
+                            name: "ask_agent_b",
+                            input: { query: "delegate to B" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "tool_use" as const,
+                },
+                {
+                    textContent: "Final from A",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            // B delegates to C
+            const mockB = createStreamingMock([
+                {
+                    textContent: undefined,
+                    toolCalls: [
+                        {
+                            id: "tool_1",
+                            name: "ask_agent_c",
+                            input: { query: "delegate to C" },
+                        },
+                    ],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "tool_use" as const,
+                },
+                {
+                    textContent: "Response from B",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            // C answers directly
+            const mockC = createStreamingMock([
+                {
+                    textContent: "Answer from C",
+                    toolCalls: [],
+                    usage: { inputTokens: 10, outputTokens: 10 },
+                    stopReason: "end_turn" as const,
+                },
+            ]);
+
+            agentA.ctx = mockCtx;
+            agentB.ctx = mockCtx;
+            agentC.ctx = mockCtx;
+
+            const toolsMapA = new Map([
+                ["ask_agent_b", new SubAgentExecutor("agentB", mockCtx)],
+            ]);
+            const toolsMapB = new Map([
+                ["ask_agent_c", new SubAgentExecutor("agentC", mockCtx)],
+            ]);
+
+            agentA.__init(new Map([["default", mockA]]), Object.fromEntries(toolsMapA) as any);
+            agentB.__init(new Map([["default", mockB]]), Object.fromEntries(toolsMapB) as any);
+            agentC.__init(new Map([["default", mockC]]), {});
+
+            (mockCtx as any).agents = { agentA, agentB, agentC };
+
+            // Execute - should succeed (depth 2 < default limit 5)
+            // A (depth 0) -> B (depth 1) -> C (depth 2) - all within limit
+            const response = agentA.run({ message: "Start chain" });
+            const result = await response.result;
+
+            expect(result.message).toBe("Final from A");
+            expect(result.subAgentCalls).toBeDefined();
+            expect(result.subAgentCalls?.length).toBe(1);
+
+            // Verify the delegation chain worked correctly
+            const bCall = result.subAgentCalls?.[0];
+            expect(bCall).toBeDefined();
+            expect(bCall?.agentId).toBe("agent-b");
+            expect(bCall?.result.message).toBe("Response from B");
+
+            // Agent B should have called Agent C (nested sub-agent call)
+            expect(bCall?.result.subAgentCalls).toBeDefined();
+            expect(bCall?.result.subAgentCalls?.length).toBe(1);
+
+            const cCall = bCall?.result.subAgentCalls?.[0];
+            expect(cCall).toBeDefined();
+            expect(cCall?.agentId).toBe("agent-c");
+            expect(cCall?.result.message).toBe("Answer from C");
+
+            // Token usage should be aggregated from all agents
+            // A: 2 calls (delegate + final) = 20 input + 20 output
+            // B: 2 calls (delegate + final) = 20 input + 20 output
+            // C: 1 call (answer) = 10 input + 10 output
+            // Total: 50 input + 50 output
+            expect(result.usage?.inputTokens).toBe(50);
+            expect(result.usage?.outputTokens).toBe(50);
+        });
+    });
+});