@db-lyon/flowkit 0.9.0 → 0.11.0

package/README.md

@@ -163,6 +163,42 @@ import { ShellTask } from '@db-lyon/flowkit';
 registry.register('shell', ShellTask as any);
 ```
 
+### AI agents
+
+Run LLM calls as steps. Flowkit has **no SDK dependencies** — you wire a
+model-agnostic `LLMProvider` onto the task context as `ctx.llm`, and two tasks
+consume it:
+
+- `agent_prompt` (`AgentPromptTask`) — single-shot prompt, with optional
+  JSON-Schema structured output (validated, with a repair re-prompt).
+- `agent` (`AgentTask`) — a tool-calling loop. Tools reference flowkit tasks,
+  flows, or other agents (or context handlers), gated by an allowlist and
+  per-tool argument validation. Multiple tool calls in a turn (including
+  parallel sub-agents) run concurrently under a cap.
+
+Reusable agents live under an `agents:` root key and run as flow steps or as
+other agents' tools, with mandatory budgets (`maxIterations`, `tokenBudget`,
+`maxAgentDepth`). Iteration and concurrency live in the agent runtime, so a flow
+stays a sequential spine with no `loop:` or parallel-step primitive.
+
+```yaml
+tasks:
+  extract:
+    class_path: agent_prompt
+    options:
+      prompt: "Pull the ticket fields from:\n${steps.1.data.text}"
+      schema:
+        type: object
+        required: [title, priority]
+        properties:
+          title: { type: string }
+          priority: { type: string, enum: [low, medium, high] }
+```
+
+Every call is hardened by a shared core: per-call `timeout` (with provider
+abort), `retries` with exponential backoff, structured-output validation +
+repair, and output-size caps. See [docs/ai-agents.md](docs/ai-agents.md).
+
 ### Nested flows
 
 A step can reference another flow instead of a task:
@@ -330,6 +366,7 @@ import { topologicalSort } from '@db-lyon/flowkit/dag';
 
 - [Getting started](docs/getting-started.md) — step-by-step setup guide
 - [Custom tasks](docs/custom-tasks.md) — writing and registering tasks
+- [AI agents](docs/ai-agents.md) — LLM prompts, structured output, tool-calling agents
 - [Configuration](docs/configuration.md) — YAML schema, layering, deep merge
 - [API reference](docs/api-reference.md) — full type and function reference
 

package/dist/config/index.d.ts

@@ -1,6 +1,6 @@
 export { deepMerge } from './deep-merge.js';
-export { TaskOptionsSchema, TaskDefinitionSchema, FlowStepSchema, FlowDefinitionSchema, EngineConfigSchema, } from './schema.js';
-export type { TaskOptions, TaskDefinition, FlowStep, FlowDefinition, EngineConfig, } from './schema.js';
+export { TaskOptionsSchema, TaskDefinitionSchema, FlowStepSchema, FlowDefinitionSchema, AgentToolSchema, AgentBudgetSchema, AgentDefinitionSchema, EngineConfigSchema, } from './schema.js';
+export type { TaskOptions, TaskDefinition, FlowStep, FlowDefinition, AgentTool, AgentBudget, AgentDefinition, EngineConfig, } from './schema.js';
 export { loadConfig, loadRawYaml, findConfigFile } from './loader.js';
 export type { LoadConfigOptions, LoadedConfig } from './loader.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,cAAc,EACd,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,cAAc,EACd,SAAS,EACT,WAAW,EACX,eAAe,EACf,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/config/index.js

@@ -1,4 +1,4 @@
 export { deepMerge } from './deep-merge.js';
-export { TaskOptionsSchema, TaskDefinitionSchema, FlowStepSchema, FlowDefinitionSchema, EngineConfigSchema, } from './schema.js';
+export { TaskOptionsSchema, TaskDefinitionSchema, FlowStepSchema, FlowDefinitionSchema, AgentToolSchema, AgentBudgetSchema, AgentDefinitionSchema, EngineConfigSchema, } from './schema.js';
 export { loadConfig, loadRawYaml, findConfigFile } from './loader.js';
 //# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAUrB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAarB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/config/schema.d.ts

@@ -86,8 +86,13 @@ export declare const FlowStepSchema: z.ZodEffects<z.ZodObject<{
     ignore_failure?: boolean | undefined;
 }>;
 export declare const FlowDefinitionSchema: z.ZodObject<{
-    description: z.ZodString;
-    steps: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+    /**
+     * Optional: a flow override (one that layers steps/hooks onto a same-named
+     * base) need not restate the description. Tolerates an explicit null.
+     */
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** Optional/defaulted so an override that only adjusts hooks/options is valid. */
+    steps: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
         task: z.ZodOptional<z.ZodString>;
         flow: z.ZodOptional<z.ZodString>;
         options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -142,7 +147,7 @@ export declare const FlowDefinitionSchema: z.ZodObject<{
         retryOn?: string | undefined;
         when?: string | boolean | undefined;
         ignore_failure?: boolean | undefined;
-    }>>;
+    }>>>;
     /** Runs before the first step. Failure fails the flow before steps execute. */
     on_start: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
         task: z.ZodOptional<z.ZodString>;
@@ -374,7 +379,6 @@ export declare const FlowDefinitionSchema: z.ZodObject<{
     /** If true, invoke rollback records from completed steps in reverse order on failure. */
     rollback_on_failure: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    description: string;
     steps: Record<string, {
         options?: Record<string, unknown> | undefined;
         task?: string | undefined;
@@ -385,6 +389,7 @@ export declare const FlowDefinitionSchema: z.ZodObject<{
         when?: string | boolean | undefined;
         ignore_failure?: boolean | undefined;
     }>;
+    description?: string | null | undefined;
     on_start?: {
         options?: Record<string, unknown> | undefined;
         task?: string | undefined;
@@ -427,8 +432,8 @@ export declare const FlowDefinitionSchema: z.ZodObject<{
     }[] | undefined;
     rollback_on_failure?: boolean | undefined;
 }, {
-    description: string;
-    steps: Record<string, {
+    description?: string | null | undefined;
+    steps?: Record<string, {
         options?: Record<string, unknown> | undefined;
         task?: string | undefined;
         flow?: string | undefined;
@@ -437,7 +442,7 @@ export declare const FlowDefinitionSchema: z.ZodObject<{
         retryOn?: string | undefined;
         when?: string | boolean | undefined;
         ignore_failure?: boolean | undefined;
-    }>;
+    }> | undefined;
     on_start?: {
         options?: Record<string, unknown> | undefined;
         task?: string | undefined;
@@ -480,6 +485,203 @@ export declare const FlowDefinitionSchema: z.ZodObject<{
     }[] | undefined;
     rollback_on_failure?: boolean | undefined;
 }>;
+/**
+ * A tool an agent may call. References an existing flowkit primitive — a `task`,
+ * a `flow`, or another `agent` — so tool dispatch reuses the registry, options,
+ * and `${...}` reference machinery rather than inventing a parallel concept.
+ * `name` (defaulted from the reference) is what the model sees.
+ */
+export declare const AgentToolSchema: z.ZodEffects<z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    task: z.ZodOptional<z.ZodString>;
+    flow: z.ZodOptional<z.ZodString>;
+    agent: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    description?: string | undefined;
+    task?: string | undefined;
+    flow?: string | undefined;
+    name?: string | undefined;
+    agent?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}, {
+    description?: string | undefined;
+    task?: string | undefined;
+    flow?: string | undefined;
+    name?: string | undefined;
+    agent?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}>, {
+    description?: string | undefined;
+    task?: string | undefined;
+    flow?: string | undefined;
+    name?: string | undefined;
+    agent?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}, {
+    description?: string | undefined;
+    task?: string | undefined;
+    flow?: string | undefined;
+    name?: string | undefined;
+    agent?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+}>;
+/**
+ * Hard bounds on an agent run. A tool-using agent with no caps is unbounded
+ * spend, so a budget is the intended companion to every agent definition.
+ */
+export declare const AgentBudgetSchema: z.ZodObject<{
+    /** Max model turns. */
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    /** Aggregate input+output token cap across the whole loop (incl. sub-agents). */
+    tokenBudget: z.ZodOptional<z.ZodNumber>;
+    /** Cap on a single tool result's serialized size, in chars. */
+    maxToolResultChars: z.ZodOptional<z.ZodNumber>;
+    /** Max tool calls run concurrently within a turn. */
+    maxConcurrency: z.ZodOptional<z.ZodNumber>;
+    /** Max depth of agent-calls-agent recursion. */
+    maxAgentDepth: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    maxIterations?: number | undefined;
+    tokenBudget?: number | undefined;
+    maxToolResultChars?: number | undefined;
+    maxConcurrency?: number | undefined;
+    maxAgentDepth?: number | undefined;
+}, {
+    maxIterations?: number | undefined;
+    tokenBudget?: number | undefined;
+    maxToolResultChars?: number | undefined;
+    maxConcurrency?: number | undefined;
+    maxAgentDepth?: number | undefined;
+}>;
+export declare const AgentDefinitionSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    /** Model identifier — provider-specific. */
+    model: z.ZodOptional<z.ZodString>;
+    /** System prompt / rules. */
+    system: z.ZodOptional<z.ZodString>;
+    /** Tools the agent may call (its allowlist). */
+    tools: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        task: z.ZodOptional<z.ZodString>;
+        flow: z.ZodOptional<z.ZodString>;
+        agent: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }, {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }>, {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }, {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }>, "many">>;
+    /** JSON Schema for the agent's final answer. */
+    schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Hard run bounds. */
+    budget: z.ZodOptional<z.ZodObject<{
+        /** Max model turns. */
+        maxIterations: z.ZodOptional<z.ZodNumber>;
+        /** Aggregate input+output token cap across the whole loop (incl. sub-agents). */
+        tokenBudget: z.ZodOptional<z.ZodNumber>;
+        /** Cap on a single tool result's serialized size, in chars. */
+        maxToolResultChars: z.ZodOptional<z.ZodNumber>;
+        /** Max tool calls run concurrently within a turn. */
+        maxConcurrency: z.ZodOptional<z.ZodNumber>;
+        /** Max depth of agent-calls-agent recursion. */
+        maxAgentDepth: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxIterations?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxToolResultChars?: number | undefined;
+        maxConcurrency?: number | undefined;
+        maxAgentDepth?: number | undefined;
+    }, {
+        maxIterations?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxToolResultChars?: number | undefined;
+        maxConcurrency?: number | undefined;
+        maxAgentDepth?: number | undefined;
+    }>>;
+    /** Sampling temperature. */
+    temperature: z.ZodOptional<z.ZodNumber>;
+    /** Per-call max output tokens. */
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+    /** Per-call timeout in ms. */
+    timeout: z.ZodOptional<z.ZodNumber>;
+    /** Transport retries per call. */
+    retries: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    tools: {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }[];
+    description?: string | undefined;
+    retries?: number | undefined;
+    model?: string | undefined;
+    system?: string | undefined;
+    schema?: Record<string, unknown> | undefined;
+    budget?: {
+        maxIterations?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxToolResultChars?: number | undefined;
+        maxConcurrency?: number | undefined;
+        maxAgentDepth?: number | undefined;
+    } | undefined;
+    temperature?: number | undefined;
+    maxTokens?: number | undefined;
+    timeout?: number | undefined;
+}, {
+    description?: string | undefined;
+    retries?: number | undefined;
+    model?: string | undefined;
+    system?: string | undefined;
+    tools?: {
+        description?: string | undefined;
+        task?: string | undefined;
+        flow?: string | undefined;
+        name?: string | undefined;
+        agent?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+    }[] | undefined;
+    schema?: Record<string, unknown> | undefined;
+    budget?: {
+        maxIterations?: number | undefined;
+        tokenBudget?: number | undefined;
+        maxToolResultChars?: number | undefined;
+        maxConcurrency?: number | undefined;
+        maxAgentDepth?: number | undefined;
+    } | undefined;
+    temperature?: number | undefined;
+    maxTokens?: number | undefined;
+    timeout?: number | undefined;
+}>;
 /** Minimal config shape the engine requires. Consumers extend with their own sections. */
 export declare const EngineConfigSchema: z.ZodObject<{
     tasks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -512,8 +714,13 @@ export declare const EngineConfigSchema: z.ZodObject<{
         reversible?: boolean | undefined;
     }>>>;
     flows: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-        description: z.ZodString;
-        steps: z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        /**
+         * Optional: a flow override (one that layers steps/hooks onto a same-named
+         * base) need not restate the description. Tolerates an explicit null.
+         */
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        /** Optional/defaulted so an override that only adjusts hooks/options is valid. */
+        steps: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
             task: z.ZodOptional<z.ZodString>;
             flow: z.ZodOptional<z.ZodString>;
             options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -568,7 +775,7 @@ export declare const EngineConfigSchema: z.ZodObject<{
             retryOn?: string | undefined;
             when?: string | boolean | undefined;
             ignore_failure?: boolean | undefined;
-        }>>;
+        }>>>;
         /** Runs before the first step. Failure fails the flow before steps execute. */
         on_start: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodObject<{
             task: z.ZodOptional<z.ZodString>;
@@ -800,7 +1007,6 @@ export declare const EngineConfigSchema: z.ZodObject<{
         /** If true, invoke rollback records from completed steps in reverse order on failure. */
         rollback_on_failure: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        description: string;
         steps: Record<string, {
             options?: Record<string, unknown> | undefined;
             task?: string | undefined;
@@ -811,6 +1017,7 @@ export declare const EngineConfigSchema: z.ZodObject<{
             when?: string | boolean | undefined;
             ignore_failure?: boolean | undefined;
         }>;
+        description?: string | null | undefined;
         on_start?: {
             options?: Record<string, unknown> | undefined;
             task?: string | undefined;
@@ -853,8 +1060,8 @@ export declare const EngineConfigSchema: z.ZodObject<{
         }[] | undefined;
         rollback_on_failure?: boolean | undefined;
     }, {
-        description: string;
-        steps: Record<string, {
+        description?: string | null | undefined;
+        steps?: Record<string, {
             options?: Record<string, unknown> | undefined;
             task?: string | undefined;
             flow?: string | undefined;
@@ -863,7 +1070,7 @@ export declare const EngineConfigSchema: z.ZodObject<{
             retryOn?: string | undefined;
             when?: string | boolean | undefined;
             ignore_failure?: boolean | undefined;
-        }>;
+        }> | undefined;
         on_start?: {
             options?: Record<string, unknown> | undefined;
             task?: string | undefined;
@@ -906,6 +1113,133 @@ export declare const EngineConfigSchema: z.ZodObject<{
         }[] | undefined;
         rollback_on_failure?: boolean | undefined;
     }>>>;
+    agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        /** Model identifier — provider-specific. */
+        model: z.ZodOptional<z.ZodString>;
+        /** System prompt / rules. */
+        system: z.ZodOptional<z.ZodString>;
+        /** Tools the agent may call (its allowlist). */
+        tools: z.ZodDefault<z.ZodArray<z.ZodEffects<z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            task: z.ZodOptional<z.ZodString>;
+            flow: z.ZodOptional<z.ZodString>;
+            agent: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, "strip", z.ZodTypeAny, {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }, {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }>, {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }, {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }>, "many">>;
+        /** JSON Schema for the agent's final answer. */
+        schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        /** Hard run bounds. */
+        budget: z.ZodOptional<z.ZodObject<{
+            /** Max model turns. */
+            maxIterations: z.ZodOptional<z.ZodNumber>;
+            /** Aggregate input+output token cap across the whole loop (incl. sub-agents). */
+            tokenBudget: z.ZodOptional<z.ZodNumber>;
+            /** Cap on a single tool result's serialized size, in chars. */
+            maxToolResultChars: z.ZodOptional<z.ZodNumber>;
+            /** Max tool calls run concurrently within a turn. */
+            maxConcurrency: z.ZodOptional<z.ZodNumber>;
+            /** Max depth of agent-calls-agent recursion. */
+            maxAgentDepth: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        }, {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        }>>;
+        /** Sampling temperature. */
+        temperature: z.ZodOptional<z.ZodNumber>;
+        /** Per-call max output tokens. */
+        maxTokens: z.ZodOptional<z.ZodNumber>;
+        /** Per-call timeout in ms. */
+        timeout: z.ZodOptional<z.ZodNumber>;
+        /** Transport retries per call. */
+        retries: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        tools: {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }[];
+        description?: string | undefined;
+        retries?: number | undefined;
+        model?: string | undefined;
+        system?: string | undefined;
+        schema?: Record<string, unknown> | undefined;
+        budget?: {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        } | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        timeout?: number | undefined;
+    }, {
+        description?: string | undefined;
+        retries?: number | undefined;
+        model?: string | undefined;
+        system?: string | undefined;
+        tools?: {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }[] | undefined;
+        schema?: Record<string, unknown> | undefined;
+        budget?: {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        } | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        timeout?: number | undefined;
+    }>>>;
 }, "strip", z.ZodTypeAny, {
     tasks: Record<string, {
         options: Record<string, unknown>;
@@ -916,7 +1250,6 @@ export declare const EngineConfigSchema: z.ZodObject<{
         reversible?: boolean | undefined;
     }>;
     flows: Record<string, {
-        description: string;
         steps: Record<string, {
             options?: Record<string, unknown> | undefined;
             task?: string | undefined;
@@ -927,6 +1260,7 @@ export declare const EngineConfigSchema: z.ZodObject<{
             when?: string | boolean | undefined;
             ignore_failure?: boolean | undefined;
         }>;
+        description?: string | null | undefined;
         on_start?: {
             options?: Record<string, unknown> | undefined;
             task?: string | undefined;
@@ -969,6 +1303,31 @@ export declare const EngineConfigSchema: z.ZodObject<{
         }[] | undefined;
         rollback_on_failure?: boolean | undefined;
     }>;
+    agents: Record<string, {
+        tools: {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }[];
+        description?: string | undefined;
+        retries?: number | undefined;
+        model?: string | undefined;
+        system?: string | undefined;
+        schema?: Record<string, unknown> | undefined;
+        budget?: {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        } | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        timeout?: number | undefined;
+    }>;
 }, {
     tasks?: Record<string, {
         options?: Record<string, unknown> | undefined;
@@ -979,8 +1338,8 @@ export declare const EngineConfigSchema: z.ZodObject<{
         reversible?: boolean | undefined;
     }> | undefined;
     flows?: Record<string, {
-        description: string;
-        steps: Record<string, {
+        description?: string | null | undefined;
+        steps?: Record<string, {
             options?: Record<string, unknown> | undefined;
             task?: string | undefined;
             flow?: string | undefined;
@@ -989,7 +1348,7 @@ export declare const EngineConfigSchema: z.ZodObject<{
             retryOn?: string | undefined;
             when?: string | boolean | undefined;
             ignore_failure?: boolean | undefined;
-        }>;
+        }> | undefined;
         on_start?: {
             options?: Record<string, unknown> | undefined;
             task?: string | undefined;
@@ -1032,10 +1391,38 @@ export declare const EngineConfigSchema: z.ZodObject<{
         }[] | undefined;
         rollback_on_failure?: boolean | undefined;
     }> | undefined;
+    agents?: Record<string, {
+        description?: string | undefined;
+        retries?: number | undefined;
+        model?: string | undefined;
+        system?: string | undefined;
+        tools?: {
+            description?: string | undefined;
+            task?: string | undefined;
+            flow?: string | undefined;
+            name?: string | undefined;
+            agent?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+        }[] | undefined;
+        schema?: Record<string, unknown> | undefined;
+        budget?: {
+            maxIterations?: number | undefined;
+            tokenBudget?: number | undefined;
+            maxToolResultChars?: number | undefined;
+            maxConcurrency?: number | undefined;
+            maxAgentDepth?: number | undefined;
+        } | undefined;
+        temperature?: number | undefined;
+        maxTokens?: number | undefined;
+        timeout?: number | undefined;
+    }> | undefined;
 }>;
 export type TaskOptions = z.infer<typeof TaskOptionsSchema>;
 export type TaskDefinition = z.infer<typeof TaskDefinitionSchema>;
 export type FlowStep = z.infer<typeof FlowStepSchema>;
 export type FlowDefinition = z.infer<typeof FlowDefinitionSchema>;
+export type AgentTool = z.infer<typeof AgentToolSchema>;
+export type AgentBudget = z.infer<typeof AgentBudgetSchema>;
+export type AgentDefinition = z.infer<typeof AgentDefinitionSchema>;
 export type EngineConfig = z.infer<typeof EngineConfigSchema>;
 //# sourceMappingURL=schema.d.ts.map

package/dist/config/schema.d.ts.map

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