@lleverage-ai/agent-sdk 0.0.1

package/dist/subagents/advanced.d.ts

@@ -0,0 +1,413 @@
+/**
+ * Advanced subagent system with context isolation and parallel execution.
+ *
+ * @packageDocumentation
+ */
+import type { LanguageModel, ToolSet } from "ai";
+import type { AgentState, TodoItem } from "../backends/state.js";
+import type { Agent, GenerateResult } from "../types.js";
+/**
+ * Enhanced subagent definition with additional capabilities.
+ *
+ * Extends the basic SubagentDefinition with:
+ * - Structured output schemas
+ * - Tool specification (subset or custom)
+ * - Interrupt conditions for human-in-the-loop
+ * - Model override
+ * - Maximum steps
+ *
+ * @category Subagents
+ */
+export interface EnhancedSubagentDefinition {
+    /** Unique type identifier for this subagent */
+    type: string;
+    /** Description of what this subagent specializes in */
+    description: string;
+    /** System prompt for this subagent */
+    systemPrompt: string;
+    /**
+     * Tools available to this subagent.
+     * - If ToolSet: use these specific tools
+     * - If string[]: subset of parent tools by name
+     * - If undefined: inherit all parent tools
+     */
+    tools?: ToolSet | string[];
+    /**
+     * Model to use for this subagent.
+     * If not specified, inherits from parent.
+     */
+    model?: LanguageModel;
+    /** Maximum steps/turns for this subagent */
+    maxSteps?: number;
+}
+/**
+ * Options for creating an isolated subagent context.
+ *
+ * @category Subagents
+ */
+export interface SubagentContextOptions {
+    /** Parent agent state to derive from */
+    parentState: AgentState;
+    /**
+     * Whether to share files with parent.
+     * @defaultValue true
+     */
+    shareFiles?: boolean;
+    /**
+     * Whether to isolate todos (give subagent empty todos).
+     * @defaultValue true
+     */
+    isolateTodos?: boolean;
+    /**
+     * Initial todos for the subagent (only used if isolateTodos is true).
+     */
+    initialTodos?: TodoItem[];
+}
+/**
+ * Isolated context for a subagent execution.
+ *
+ * @category Subagents
+ */
+export interface SubagentContext {
+    /** The subagent's isolated state */
+    state: AgentState;
+    /** Reference to the parent state (for merging back) */
+    parentState: AgentState;
+    /** Whether files are shared with parent */
+    filesShared: boolean;
+    /** Whether todos are isolated */
+    todosIsolated: boolean;
+}
+/**
+ * Options for executing a subagent.
+ *
+ * @category Subagents
+ */
+export interface SubagentExecutionOptions {
+    /** The subagent definition to execute */
+    definition: EnhancedSubagentDefinition;
+    /** The task/prompt for the subagent */
+    prompt: string;
+    /** Parent agent for inheriting configuration */
+    parentAgent: Agent;
+    /**
+     * Isolated context for the subagent.
+     * If not provided, context is created automatically.
+     */
+    context?: SubagentContext;
+    /**
+     * Maximum tokens for generation.
+     * If not specified, uses definition.maxSteps * 4096.
+     */
+    maxTokens?: number;
+    /**
+     * Abort signal for cancellation.
+     */
+    signal?: AbortSignal;
+    /**
+     * Callback when the subagent starts.
+     */
+    onStart?: (event: SubagentStartEvent) => void;
+    /**
+     * Callback for each step the subagent takes.
+     */
+    onStep?: (event: SubagentStepEvent) => void;
+    /**
+     * Callback when the subagent finishes.
+     */
+    onFinish?: (event: SubagentFinishEvent) => void;
+    /**
+     * Callback when an error occurs.
+     */
+    onError?: (event: SubagentErrorEvent) => void;
+}
+/**
+ * Result from executing a subagent.
+ *
+ * @category Subagents
+ */
+export interface SubagentExecutionResult {
+    /** Whether execution succeeded */
+    success: boolean;
+    /** The generated text response */
+    text: string;
+    /** Structured output if schema was provided */
+    output?: unknown;
+    /** Number of steps taken */
+    steps: number;
+    /** Why generation finished */
+    finishReason: string;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Error message if failed */
+    error?: string;
+    /** The subagent's final context (for merging back) */
+    context: SubagentContext;
+    /** Full generation result */
+    result?: GenerateResult;
+}
+/**
+ * Result from parallel subagent execution.
+ *
+ * @category Subagents
+ */
+export interface ParallelExecutionResult {
+    /** Individual results for each subagent */
+    results: SubagentExecutionResult[];
+    /** Number of successful executions */
+    successCount: number;
+    /** Number of failed executions */
+    failureCount: number;
+    /** Total duration (max of individual durations) */
+    totalDuration: number;
+    /** Whether all executions succeeded */
+    allSucceeded: boolean;
+}
+/**
+ * Base event for subagent lifecycle.
+ *
+ * @category Subagents
+ */
+export interface SubagentEvent {
+    /** Unique identifier for this execution */
+    executionId: string;
+    /** The subagent type */
+    subagentType: string;
+    /** Timestamp of the event */
+    timestamp: string;
+}
+/**
+ * Event emitted when a subagent starts.
+ *
+ * @category Subagents
+ */
+export interface SubagentStartEvent extends SubagentEvent {
+    type: "subagent-start";
+    /** The task prompt */
+    prompt: string;
+}
+/**
+ * Event emitted for each subagent step.
+ *
+ * @category Subagents
+ */
+export interface SubagentStepEvent extends SubagentEvent {
+    type: "subagent-step";
+    /** Step number (1-indexed) */
+    stepNumber: number;
+    /** Tool calls made in this step */
+    toolCalls: Array<{
+        toolName: string;
+        args: unknown;
+        result: unknown;
+    }>;
+    /** Text generated in this step */
+    text: string;
+}
+/**
+ * Event emitted when a subagent finishes.
+ *
+ * @category Subagents
+ */
+export interface SubagentFinishEvent extends SubagentEvent {
+    type: "subagent-finish";
+    /** Whether execution succeeded */
+    success: boolean;
+    /** Summary of the result */
+    summary: string;
+    /** Total steps taken */
+    steps: number;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Finish reason */
+    finishReason: string;
+}
+/**
+ * Event emitted when an error occurs.
+ *
+ * @category Subagents
+ */
+export interface SubagentErrorEvent extends SubagentEvent {
+    type: "subagent-error";
+    /** The error that occurred */
+    error: Error;
+    /** Step number where error occurred (if applicable) */
+    stepNumber?: number;
+}
+/**
+ * Event emitter interface for subagent events.
+ *
+ * @category Subagents
+ */
+export interface SubagentEventEmitter {
+    /** Register a listener for start events */
+    onStart(handler: (event: SubagentStartEvent) => void): void;
+    /** Register a listener for step events */
+    onStep(handler: (event: SubagentStepEvent) => void): void;
+    /** Register a listener for finish events */
+    onFinish(handler: (event: SubagentFinishEvent) => void): void;
+    /** Register a listener for error events */
+    onError(handler: (event: SubagentErrorEvent) => void): void;
+    /** Remove all listeners */
+    removeAllListeners(): void;
+}
+/**
+ * Creates an isolated context for subagent execution.
+ *
+ * By default:
+ * - Files are shared (subagent sees parent's files)
+ * - Todos are isolated (subagent gets empty todos)
+ *
+ * This follows the DeepAgentSDK pattern where files represent shared
+ * work product but todos represent the agent's internal planning.
+ *
+ * @param options - Context creation options
+ * @returns Isolated subagent context
+ *
+ * @example
+ * ```typescript
+ * const context = createSubagentContext({
+ *   parentState: parentAgent.state,
+ *   shareFiles: true,
+ *   isolateTodos: true,
+ * });
+ *
+ * // Subagent can see parent's files
+ * // Subagent has empty todos
+ * ```
+ *
+ * @category Subagents
+ */
+export declare function createSubagentContext(options: SubagentContextOptions): SubagentContext;
+/**
+ * Merges subagent context changes back to parent.
+ *
+ * Only file changes are merged back (if files were shared).
+ * Todo changes are NOT merged (todos are isolated by design).
+ *
+ * @param context - The subagent context to merge
+ *
+ * @example
+ * ```typescript
+ * // After subagent completes
+ * mergeSubagentContext(result.context);
+ *
+ * // Parent now has any files the subagent created/modified
+ * ```
+ *
+ * @category Subagents
+ */
+export declare function mergeSubagentContext(context: SubagentContext): void;
+/**
+ * Executes a subagent with isolated context.
+ *
+ * Creates a subagent from the definition, executes the prompt,
+ * and returns the result with the final context for merging.
+ *
+ * @param options - Execution options
+ * @returns Execution result with context
+ *
+ * @example
+ * ```typescript
+ * const result = await executeSubagent({
+ *   definition: {
+ *     type: "researcher",
+ *     description: "Researches topics",
+ *     systemPrompt: "You are a research assistant.",
+ *   },
+ *   prompt: "Research the history of TypeScript",
+ *   parentAgent,
+ *   hooks,
+ *   onStep: (event) => console.log(`Step ${event.stepNumber}`),
+ * });
+ *
+ * if (result.success) {
+ *   mergeSubagentContext(result.context);
+ *   console.log(result.text);
+ * }
+ * ```
+ *
+ * @category Subagents
+ */
+export declare function executeSubagent(options: SubagentExecutionOptions): Promise<SubagentExecutionResult>;
+/**
+ * Options for a single parallel execution task.
+ *
+ * @category Subagents
+ */
+export interface ParallelTask {
+    /** The subagent definition */
+    definition: EnhancedSubagentDefinition;
+    /** The prompt for this task */
+    prompt: string;
+}
+/**
+ * Executes multiple subagents in parallel.
+ *
+ * All subagents share the same parent context initially.
+ * After completion, file changes from all subagents are merged back.
+ *
+ * Note: If multiple subagents modify the same file, the last one wins.
+ * For better conflict handling, consider using different file paths.
+ *
+ * @param tasks - Array of tasks to execute
+ * @param parentAgent - Parent agent for configuration
+ * @param onResult - Optional callback for each completed task
+ * @returns Combined results from all executions
+ *
+ * @example
+ * ```typescript
+ * const results = await executeSubagentsParallel(
+ *   [
+ *     {
+ *       definition: researcherDef,
+ *       prompt: "Research TypeScript history",
+ *     },
+ *     {
+ *       definition: coderDef,
+ *       prompt: "Write a utility function",
+ *     },
+ *   ],
+ *   parentAgent,
+ *   (result, index) => console.log(`Task ${index} completed`),
+ * );
+ *
+ * console.log(`${results.successCount}/${results.results.length} succeeded`);
+ * ```
+ *
+ * @category Subagents
+ */
+export declare function executeSubagentsParallel(tasks: ParallelTask[], parentAgent: Agent, onResult?: (result: SubagentExecutionResult, index: number) => void): Promise<ParallelExecutionResult>;
+/**
+ * Creates an event emitter for subagent lifecycle events.
+ *
+ * Provides a convenient way to handle all subagent events
+ * without passing individual callbacks.
+ *
+ * @returns Event emitter instance
+ *
+ * @example
+ * ```typescript
+ * const emitter = createSubagentEventEmitter();
+ *
+ * emitter.onStart((event) => {
+ *   console.log(`Starting ${event.subagentType}: ${event.prompt}`);
+ * });
+ *
+ * emitter.onStep((event) => {
+ *   console.log(`Step ${event.stepNumber}: ${event.toolCalls.length} tool calls`);
+ * });
+ *
+ * emitter.onFinish((event) => {
+ *   console.log(`Finished in ${event.duration}ms: ${event.summary}`);
+ * });
+ *
+ * emitter.onError((event) => {
+ *   console.error(`Error: ${event.error.message}`);
+ * });
+ * ```
+ *
+ * @category Subagents
+ */
+export declare function createSubagentEventEmitter(): SubagentEventEmitter;
+//# sourceMappingURL=advanced.d.ts.map

package/dist/subagents/advanced.d.ts.map

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