@swirls/looms 0.4.0 → 0.5.1

package/dist/agent/effects.d.ts

@@ -19,8 +19,30 @@ export declare const callLlmEffect: NoInfer<import("@swirls/looms/core").EffectD
         }[] | undefined;
     }[] | undefined;
     readonly input?: Schema.Json | undefined;
+    readonly structuredOutput?: Schema.Json | undefined;
+    readonly alreadyCompacted?: boolean | undefined;
     readonly consumedSteerMessageIds?: readonly string[] | undefined;
 }, AgentDefinitionsTag | LlmTag, (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "agent.context.compacted";
+    readonly payload: {
+        readonly turn: number;
+        readonly originalCount: number;
+        readonly compactedCount: number;
+        readonly summary?: string | undefined;
+        readonly reason?: "manual" | "overflow" | "threshold" | undefined;
+        readonly messages?: readonly {
+            readonly role: "assistant" | "system" | "tool" | "user";
+            readonly content: string;
+            readonly toolCallId?: string | undefined;
+            readonly name?: string | undefined;
+            readonly toolCalls?: {
+                readonly id: string;
+                readonly name: string;
+                readonly arguments: Schema.Json;
+            }[] | undefined;
+        }[] | undefined;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "agent.effects.requested";
     readonly payload: {
         readonly toolCallId: string;
@@ -59,6 +81,9 @@ export declare const callLlmEffect: NoInfer<import("@swirls/looms/core").EffectD
                     readonly actorId?: string | undefined;
                 } | {
                     readonly type: "system";
+                } | {
+                    readonly type: "run";
+                    readonly runId: string;
                 } | undefined;
                 readonly ephemeral?: boolean | undefined;
                 readonly id?: string | undefined;
@@ -76,16 +101,35 @@ export declare const callLlmEffect: NoInfer<import("@swirls/looms/core").EffectD
             readonly type: "runtime.cancel";
             readonly threadId: string;
             readonly tag?: string | undefined;
+        } | {
+            readonly type: "runtime.launch";
+            readonly runId: string;
+            readonly kind: string;
+            readonly definitionName: string;
+            readonly definitionVersion: string;
+            readonly input: Schema.Json;
+            readonly close: "terminate" | "wait";
+            readonly tag?: string | undefined;
+        } | {
+            readonly type: "runtime.cancelRun";
+            readonly runId: string;
+            readonly tag?: string | undefined;
         } | {
             readonly type: string;
             readonly input: Schema.Json;
             readonly tag?: string | undefined;
+            readonly at?: number | undefined;
         })[];
         readonly waitOn?: {
             readonly type: string | readonly string[];
             readonly match?: Schema.Json | undefined;
         } | undefined;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "agent.lineage";
+    readonly payload: {
+        readonly depth: number;
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "agent.message";
     readonly payload: {
@@ -160,6 +204,7 @@ export declare const callLlmEffect: NoInfer<import("@swirls/looms/core").EffectD
         readonly definitionVersion: string;
         readonly toolCallId: string;
         readonly input: Schema.Json;
+        readonly depth?: number | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "agent.steered";
@@ -212,6 +257,26 @@ export declare const callLlmEffect: NoInfer<import("@swirls/looms/core").EffectD
         readonly turn: number;
         readonly delta: string;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "agent.turn.usage";
+    readonly payload: {
+        readonly turn: number;
+        readonly input: number;
+        readonly output: number;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.child.close.requested";
+    readonly payload: {
+        readonly policy: "terminate" | "wait";
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.child.settled";
+    readonly payload: {
+        readonly runId: string;
+        readonly status: "cancelled" | "completed" | "failed";
+        readonly output: Schema.Json;
+        readonly error: string | null;
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.effect.ambiguous";
     readonly payload: {
@@ -256,6 +321,8 @@ export declare const callLlmEffect: NoInfer<import("@swirls/looms/core").EffectD
     readonly payload: {
         readonly effectId: string;
         readonly error: string;
+        readonly nonRetryable?: boolean | undefined;
+        readonly retryAfterMs?: number | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.effect.heartbeat";
@@ -264,6 +331,7 @@ export declare const callLlmEffect: NoInfer<import("@swirls/looms/core").EffectD
         readonly attempt: number;
         readonly heartbeatAt: number;
         readonly deadlineAt: number | null;
+        readonly details?: Schema.Json | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.effect.queued";
@@ -316,6 +384,16 @@ export declare const callLlmEffect: NoInfer<import("@swirls/looms/core").EffectD
         readonly sourceRunId: string;
         readonly sourceSeq: number;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.run.launched";
+    readonly payload: {
+        readonly runId: string;
+        readonly kind: string;
+        readonly definitionName: string;
+        readonly definitionVersion: string;
+        readonly effectId: string;
+        readonly close: "terminate" | "wait";
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.run.started";
     readonly payload: {
@@ -325,6 +403,20 @@ export declare const callLlmEffect: NoInfer<import("@swirls/looms/core").EffectD
         readonly definitionVersion: string;
         readonly input: Schema.Json;
         readonly requestedThreadId?: string | null | undefined;
+        readonly launchedBy?: {
+            readonly runId: string;
+            readonly threadId: string;
+            readonly effectId: string;
+            readonly causationId: string;
+            readonly causationSeq: number;
+        } | undefined;
+        readonly attributes?: {
+            readonly [x: string]: string;
+        } | undefined;
+        readonly trace?: {
+            readonly traceparent: string;
+            readonly tracestate?: string | undefined;
+        } | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.signal.received";
@@ -419,7 +511,29 @@ export declare const executeToolEffect: NoInfer<import("@swirls/looms/core").Eff
         readonly name: string;
         readonly arguments: Schema.Json;
     };
+    readonly input?: Schema.Json | undefined;
+    readonly depth?: number | undefined;
 }, AgentDefinitionsTag, (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "agent.context.compacted";
+    readonly payload: {
+        readonly turn: number;
+        readonly originalCount: number;
+        readonly compactedCount: number;
+        readonly summary?: string | undefined;
+        readonly reason?: "manual" | "overflow" | "threshold" | undefined;
+        readonly messages?: readonly {
+            readonly role: "assistant" | "system" | "tool" | "user";
+            readonly content: string;
+            readonly toolCallId?: string | undefined;
+            readonly name?: string | undefined;
+            readonly toolCalls?: {
+                readonly id: string;
+                readonly name: string;
+                readonly arguments: Schema.Json;
+            }[] | undefined;
+        }[] | undefined;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "agent.effects.requested";
     readonly payload: {
         readonly toolCallId: string;
@@ -458,6 +572,9 @@ export declare const executeToolEffect: NoInfer<import("@swirls/looms/core").Eff
                     readonly actorId?: string | undefined;
                 } | {
                     readonly type: "system";
+                } | {
+                    readonly type: "run";
+                    readonly runId: string;
                 } | undefined;
                 readonly ephemeral?: boolean | undefined;
                 readonly id?: string | undefined;
@@ -475,16 +592,35 @@ export declare const executeToolEffect: NoInfer<import("@swirls/looms/core").Eff
             readonly type: "runtime.cancel";
             readonly threadId: string;
             readonly tag?: string | undefined;
+        } | {
+            readonly type: "runtime.launch";
+            readonly runId: string;
+            readonly kind: string;
+            readonly definitionName: string;
+            readonly definitionVersion: string;
+            readonly input: Schema.Json;
+            readonly close: "terminate" | "wait";
+            readonly tag?: string | undefined;
+        } | {
+            readonly type: "runtime.cancelRun";
+            readonly runId: string;
+            readonly tag?: string | undefined;
         } | {
             readonly type: string;
             readonly input: Schema.Json;
             readonly tag?: string | undefined;
+            readonly at?: number | undefined;
         })[];
         readonly waitOn?: {
             readonly type: string | readonly string[];
             readonly match?: Schema.Json | undefined;
         } | undefined;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "agent.lineage";
+    readonly payload: {
+        readonly depth: number;
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "agent.message";
     readonly payload: {
@@ -559,6 +695,7 @@ export declare const executeToolEffect: NoInfer<import("@swirls/looms/core").Eff
         readonly definitionVersion: string;
         readonly toolCallId: string;
         readonly input: Schema.Json;
+        readonly depth?: number | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "agent.steered";
@@ -611,6 +748,26 @@ export declare const executeToolEffect: NoInfer<import("@swirls/looms/core").Eff
         readonly turn: number;
         readonly delta: string;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "agent.turn.usage";
+    readonly payload: {
+        readonly turn: number;
+        readonly input: number;
+        readonly output: number;
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.child.close.requested";
+    readonly payload: {
+        readonly policy: "terminate" | "wait";
+    };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.child.settled";
+    readonly payload: {
+        readonly runId: string;
+        readonly status: "cancelled" | "completed" | "failed";
+        readonly output: Schema.Json;
+        readonly error: string | null;
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.effect.ambiguous";
     readonly payload: {
@@ -655,6 +812,8 @@ export declare const executeToolEffect: NoInfer<import("@swirls/looms/core").Eff
     readonly payload: {
         readonly effectId: string;
         readonly error: string;
+        readonly nonRetryable?: boolean | undefined;
+        readonly retryAfterMs?: number | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.effect.heartbeat";
@@ -663,6 +822,7 @@ export declare const executeToolEffect: NoInfer<import("@swirls/looms/core").Eff
         readonly attempt: number;
         readonly heartbeatAt: number;
         readonly deadlineAt: number | null;
+        readonly details?: Schema.Json | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.effect.queued";
@@ -715,6 +875,16 @@ export declare const executeToolEffect: NoInfer<import("@swirls/looms/core").Eff
         readonly sourceRunId: string;
         readonly sourceSeq: number;
     };
+}) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
+    readonly type: "runtime.run.launched";
+    readonly payload: {
+        readonly runId: string;
+        readonly kind: string;
+        readonly definitionName: string;
+        readonly definitionVersion: string;
+        readonly effectId: string;
+        readonly close: "terminate" | "wait";
+    };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.run.started";
     readonly payload: {
@@ -724,6 +894,20 @@ export declare const executeToolEffect: NoInfer<import("@swirls/looms/core").Eff
         readonly definitionVersion: string;
         readonly input: Schema.Json;
         readonly requestedThreadId?: string | null | undefined;
+        readonly launchedBy?: {
+            readonly runId: string;
+            readonly threadId: string;
+            readonly effectId: string;
+            readonly causationId: string;
+            readonly causationSeq: number;
+        } | undefined;
+        readonly attributes?: {
+            readonly [x: string]: string;
+        } | undefined;
+        readonly trace?: {
+            readonly traceparent: string;
+            readonly tracestate?: string | undefined;
+        } | undefined;
     };
 }) | (Omit<import("@swirls/looms/core").EventInput, "payload" | "type"> & {
     readonly type: "runtime.signal.received";

package/dist/agent/effects.js

@@ -1,6 +1,6 @@
 import { Data, Effect, Predicate, Schema } from 'effect';
 import { createThreadId, DEFAULT_DEFINITION_VERSION, validateInputEffect, } from '@swirls/looms/core';
-import { normalizeTools } from './definitions.js';
+import { buildStructuredOutputInstructions, defaultAgentCompactor, defineTool, isContextOverflowError, normalizeTools, STRUCTURED_OUTPUT_TOOL_NAME, TEAM_MEMBER_MAX_DEPTH, } from './definitions.js';
 import { AgentDefinitionsTag } from './definitions-store.js';
 import { LlmTag } from './llm.js';
 import { agentModule } from './scope.js';
@@ -12,6 +12,8 @@ const CallLlmInput = Schema.Struct({
     definitionVersion: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_DEFINITION_VERSION))),
     messages: Schema.optional(Schema.Array(MessageSchema)),
     input: Schema.optional(Schema.Json),
+    structuredOutput: Schema.optional(Schema.NullOr(Schema.Json)),
+    alreadyCompacted: Schema.optional(Schema.Boolean),
     consumedSteerMessageIds: Schema.optional(Schema.Array(Schema.String)),
 });
 const ExecuteToolInput = Schema.Struct({
@@ -19,6 +21,8 @@ const ExecuteToolInput = Schema.Struct({
     definitionName: Schema.optional(Schema.String),
     definitionVersion: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_DEFINITION_VERSION))),
     toolCall: ToolCallSchema,
+    input: Schema.optional(Schema.Json),
+    depth: Schema.optional(Schema.Finite),
 });
 class AgentExecutionError extends Data.TaggedError('AgentExecutionError') {
     constructor(operation, cause) {
@@ -33,6 +37,41 @@ class AgentExecutionError extends Data.TaggedError('AgentExecutionError') {
 function findTool(tools, name) {
     return tools.find((tool) => tool.name === name);
 }
+/** Static tools, then `resolveTools`, then `submit_output` when the agent declares an output. */
+function agentTools(definition, ctx) {
+    return Effect.gen(function* () {
+        const tools = normalizeTools(definition.tools);
+        if (definition.resolveTools) {
+            const resolved = yield* Effect.tryPromise({
+                try: () => Promise.resolve(definition.resolveTools(ctx)),
+                catch: (cause) => new AgentExecutionError('resolve tools', cause),
+            });
+            tools.push(...normalizeTools(resolved));
+        }
+        if (definition.output) {
+            tools.push(defineTool({
+                name: STRUCTURED_OUTPUT_TOOL_NAME,
+                description: 'Submit the final structured output for this task. Call it once all work is done, with values that match the output schema.',
+                input: definition.output,
+                handler: (output) => ({ accepted: true, output }),
+            }));
+        }
+        return tools;
+    });
+}
+function toolError(input, threadId, error) {
+    return {
+        type: 'agent.tool.result',
+        payload: {
+            turn: input.turn,
+            toolCallId: input.toolCall.id,
+            name: input.toolCall.name,
+            result: null,
+            error,
+        },
+        threadId,
+    };
+}
 export const callLlmEffect = agentModule.effect({
     type: 'agent.callLLM',
     input: CallLlmInput,
@@ -42,6 +81,8 @@ export const callLlmEffect = agentModule.effect({
         definitionVersion: input.definitionVersion,
         messages: [...(input.messages ?? [])],
         input: input.input ?? null,
+        structuredOutput: input.structuredOutput ?? null,
+        alreadyCompacted: input.alreadyCompacted ?? false,
         consumedSteerMessageIds: [...(input.consumedSteerMessageIds ?? [])],
         runId: ctx.runId,
         threadId: ctx.threadId,
@@ -51,10 +92,12 @@ export const callLlmEffect = agentModule.effect({
 });
 function runCallLlm(args) {
     return Effect.gen(function* () {
-        const { turn, threadId, emit, definitionName, definitionVersion, messages, input, consumedSteerMessageIds, signal, } = args;
+        const { turn, threadId, emit, definitionName, definitionVersion, messages, input, structuredOutput, consumedSteerMessageIds, signal, } = args;
         const agents = yield* AgentDefinitionsTag;
         const llm = yield* LlmTag;
-        const definition = definitionName ? agents.get(definitionName, definitionVersion) : undefined;
+        const definition = definitionName
+            ? yield* agents.resolve(definitionName, definitionVersion)
+            : undefined;
         if (!definition) {
             return [
                 {
@@ -73,32 +116,59 @@ function runCallLlm(args) {
                 },
             ];
         }
-        const tools = normalizeTools(definition.tools);
-        const events = [
-            {
-                type: 'agent.turn.started',
-                payload: { turn },
-                threadId,
-            },
-        ];
+        const tools = yield* agentTools(definition, { threadId, turn, input });
+        const instructions = definition.output
+            ? `${definition.instructions}\n\n${buildStructuredOutputInstructions(STRUCTURED_OUTPUT_TOOL_NAME)}`
+            : definition.instructions;
         const turnCtx = {
             threadId,
             turn,
             messages,
             input,
             tools,
-            instructions: definition.instructions,
+            instructions,
             signal,
         };
-        const result = definition.runTurn
-            ? yield* Effect.tryPromise({
-                try: () => Promise.resolve(definition.runTurn(turnCtx)),
-                catch: (cause) => new AgentExecutionError('run agent turn', cause),
-            })
-            : yield* llm.complete({
+        if (definition.assertCredits) {
+            const creditCheck = yield* Effect.tryPromise({
+                try: () => Promise.resolve(definition.assertCredits(turnCtx)),
+                catch: (cause) => new AgentExecutionError('credit gate check', cause),
+            }).pipe(Effect.match({
+                onFailure: (error) => ({ ok: false, error: error.message }),
+                onSuccess: () => ({ ok: true }),
+            }));
+            if (!creditCheck.ok) {
+                return [
+                    {
+                        type: 'runtime.thread.failed',
+                        payload: { threadId, error: creditCheck.error },
+                        threadId,
+                    },
+                ];
+            }
+        }
+        const events = [
+            {
+                type: 'agent.turn.started',
+                payload: { turn },
+                threadId,
+            },
+        ];
+        const executeTurn = (turnMessages) => {
+            if (definition.runTurn) {
+                return Effect.tryPromise({
+                    try: () => Promise.resolve(definition.runTurn({
+                        ...turnCtx,
+                        messages: [...turnMessages],
+                        instructions,
+                    })),
+                    catch: (cause) => new AgentExecutionError('run agent turn', cause),
+                });
+            }
+            return llm.complete({
                 model: definition.model,
-                instructions: definition.instructions,
-                messages: [{ role: 'system', content: definition.instructions }, ...turnCtx.messages],
+                instructions,
+                messages: [{ role: 'system', content: instructions }, ...turnMessages],
                 tools,
                 toolSpecs: toolSpecs(tools),
                 signal,
@@ -109,11 +179,48 @@ function runCallLlm(args) {
                     ephemeral: true,
                 }),
             });
+        };
+        let currentMessages = turnCtx.messages;
+        const result = yield* executeTurn(currentMessages).pipe(Effect.matchEffect({
+            onFailure: (err) => {
+                if (isContextOverflowError(err) && !args.alreadyCompacted) {
+                    return Effect.gen(function* () {
+                        const compactor = definition.compact ?? defaultAgentCompactor;
+                        const originalCount = currentMessages.length;
+                        const compacted = yield* Effect.tryPromise({
+                            try: () => Promise.resolve(compactor({
+                                threadId,
+                                turn,
+                                messages: currentMessages,
+                                reason: 'overflow',
+                            })),
+                            catch: (cause) => new AgentExecutionError('context compaction', cause),
+                        });
+                        events.push({
+                            type: 'agent.context.compacted',
+                            payload: {
+                                turn,
+                                originalCount,
+                                compactedCount: compacted.messages.length,
+                                summary: compacted.summary,
+                                reason: 'overflow',
+                                messages: [...compacted.messages],
+                            },
+                            threadId,
+                        });
+                        currentMessages = [...compacted.messages];
+                        return yield* executeTurn(currentMessages);
+                    });
+                }
+                return Effect.fail(err);
+            },
+            onSuccess: (res) => Effect.succeed(res),
+        }));
         const toolCalls = result.toolCalls ?? result.message.toolCalls ?? [];
         const shouldStop = definition.stopWhen?.({
             turn,
             maxTurns: definition.maxTurns ?? 20,
-            messages: turnCtx.messages,
+            messages: currentMessages,
             toolCalls,
             result,
         });
@@ -126,9 +233,26 @@ function runCallLlm(args) {
             },
             threadId,
         });
+        if (result.usage) {
+            events.push({
+                type: 'agent.turn.usage',
+                payload: {
+                    turn,
+                    input: result.usage.input,
+                    output: result.usage.output,
+                },
+                threadId,
+            });
+            if (definition.trackUsage) {
+                yield* Effect.tryPromise({
+                    try: () => Promise.resolve(definition.trackUsage({ input: result.usage.input, output: result.usage.output, turn }, turnCtx)),
+                    catch: (cause) => new AgentExecutionError('track usage', cause),
+                }).pipe(Effect.catch((error) => Effect.logWarning('[@swirls/looms/agent] trackUsage failed', error)));
+            }
+        }
         if (shouldStop) {
             if (!definition.conversational) {
-                const output = result.output ?? { text: result.message.content };
+                const output = structuredOutput ?? result.output ?? { text: result.message.content };
                 events.push({
                     type: 'runtime.thread.completed',
                     payload: {
@@ -148,7 +272,7 @@ function runCallLlm(args) {
             });
         }
         if (toolCalls.length === 0 && !definition.conversational) {
-            const output = result.output ?? { text: result.message.content };
+            const output = structuredOutput ?? result.output ?? { text: result.message.content };
             events.push({
                 type: 'runtime.thread.completed',
                 payload: {
@@ -168,7 +292,7 @@ export const executeToolEffect = agentModule.effect({
         const threadId = ctx.threadId;
         const agents = yield* AgentDefinitionsTag;
         const definition = input.definitionName
-            ? agents.get(input.definitionName, input.definitionVersion)
+            ? yield* agents.resolve(input.definitionName, input.definitionVersion)
             : undefined;
         if (!definition) {
             return [
@@ -185,22 +309,20 @@ export const executeToolEffect = agentModule.effect({
                 },
             ];
         }
-        const tools = normalizeTools(definition.tools);
-        const tool = findTool(tools, input.toolCall.name);
+        const resolved = yield* agentTools(definition, {
+            threadId,
+            turn: input.turn,
+            input: input.input ?? null,
+        }).pipe(Effect.match({
+            onFailure: (error) => ({ ok: false, error: error.message }),
+            onSuccess: (tools) => ({ ok: true, tools }),
+        }));
+        if (!resolved.ok) {
+            return [toolError(input, threadId, `Could not resolve tools: ${resolved.error}`)];
+        }
+        const tool = findTool(resolved.tools, input.toolCall.name);
         if (!tool) {
-            return [
-                {
-                    type: 'agent.tool.result',
-                    payload: {
-                        turn: input.turn,
-                        toolCallId: input.toolCall.id,
-                        name: input.toolCall.name,
-                        result: null,
-                        error: `Unknown tool: ${input.toolCall.name}`,
-                    },
-                    threadId,
-                },
-            ];
+            return [toolError(input, threadId, `Unknown tool: ${input.toolCall.name}`)];
         }
         switch (tool.kind) {
             case 'function': {
@@ -209,6 +331,7 @@ export const executeToolEffect = agentModule.effect({
                     onSuccess: (value) => ({ ok: true, value }),
                 }));
                 if (!validated.ok) {
+                    const isSubmit = tool.name === STRUCTURED_OUTPUT_TOOL_NAME;
                     return [
                         {
                             type: 'agent.tool.result',
@@ -217,7 +340,9 @@ export const executeToolEffect = agentModule.effect({
                                 toolCallId: input.toolCall.id,
                                 name: input.toolCall.name,
                                 result: null,
-                                error: validated.error,
+                                error: isSubmit
+                                    ? `Output validation failed: ${validated.error}. Fix the fields and call ${STRUCTURED_OUTPUT_TOOL_NAME} again.`
+                                    : validated.error,
                             },
                             threadId,
                         },
@@ -248,6 +373,12 @@ export const executeToolEffect = agentModule.effect({
                 ];
             }
             case 'thread': {
+                const depth = input.depth ?? 0;
+                if (depth >= TEAM_MEMBER_MAX_DEPTH) {
+                    return [
+                        toolError(input, threadId, `Subagent depth limit reached (max depth: ${TEAM_MEMBER_MAX_DEPTH})`),
+                    ];
+                }
                 const validated = tool.input
                     ? yield* validateInputEffect(tool.input, input.toolCall.arguments).pipe(Effect.match({
                         onFailure: (error) => ({ ok: false, error: error.message }),
@@ -281,6 +412,7 @@ export const executeToolEffect = agentModule.effect({
                             definitionVersion: tool.childVersion,
                             input: childInput,
                             toolCallId: input.toolCall.id,
+                            depth: depth + 1,
                         },
                         threadId,
                     },