@agentionai/agents 0.4.1 → 0.6.0

package/dist/graph/context/ContextStore.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Simple key-value store for sharing data between agents in a graph.
+ * Accessed via tools with descriptive keys.
+ *
+ * @example
+ * ```typescript
+ * const store = new ContextStore({ userId: '123' });
+ * store.set('research_findings', { topic: 'AI', summary: '...' });
+ * const findings = store.get<{ topic: string; summary: string }>('research_findings');
+ * ```
+ */
+export declare class ContextStore {
+    private store;
+    /**
+     * Create a new ContextStore with optional initial values.
+     * @param initial - Initial key-value pairs to populate the store
+     */
+    constructor(initial?: Record<string, unknown>);
+    /**
+     * Set a value with a descriptive key.
+     * @param key - A descriptive key for this value (e.g., "research_findings", "user_preferences")
+     * @param value - The value to store
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * Get a value by key.
+     * @param key - The key to retrieve
+     * @returns The value if found, undefined otherwise
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Check if a key exists in the store.
+     * @param key - The key to check
+     * @returns True if the key exists
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a key from the store.
+     * @param key - The key to delete
+     * @returns True if the key was deleted, false if it didn't exist
+     */
+    delete(key: string): boolean;
+    /**
+     * Get all keys in the store.
+     * @returns Array of all keys
+     */
+    keys(): string[];
+    /**
+     * Get the number of entries in the store.
+     * @returns The number of entries
+     */
+    get size(): number;
+    /**
+     * Get all entries as a plain object.
+     * @returns Object with all key-value pairs
+     */
+    toObject(): Record<string, unknown>;
+    /**
+     * Clear all entries from the store.
+     */
+    clear(): void;
+    /**
+     * Create a clone of this context store.
+     * Note: This performs a shallow clone of values.
+     * @returns A new ContextStore with the same entries
+     */
+    clone(): ContextStore;
+}
+//# sourceMappingURL=ContextStore.d.ts.map

package/dist/graph/context/ContextStore.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextStore = void 0;
+/**
+ * Simple key-value store for sharing data between agents in a graph.
+ * Accessed via tools with descriptive keys.
+ *
+ * @example
+ * ```typescript
+ * const store = new ContextStore({ userId: '123' });
+ * store.set('research_findings', { topic: 'AI', summary: '...' });
+ * const findings = store.get<{ topic: string; summary: string }>('research_findings');
+ * ```
+ */
+class ContextStore {
+    /**
+     * Create a new ContextStore with optional initial values.
+     * @param initial - Initial key-value pairs to populate the store
+     */
+    constructor(initial) {
+        this.store = new Map();
+        if (initial) {
+            for (const [key, value] of Object.entries(initial)) {
+                this.store.set(key, value);
+            }
+        }
+    }
+    /**
+     * Set a value with a descriptive key.
+     * @param key - A descriptive key for this value (e.g., "research_findings", "user_preferences")
+     * @param value - The value to store
+     */
+    set(key, value) {
+        this.store.set(key, value);
+    }
+    /**
+     * Get a value by key.
+     * @param key - The key to retrieve
+     * @returns The value if found, undefined otherwise
+     */
+    get(key) {
+        return this.store.get(key);
+    }
+    /**
+     * Check if a key exists in the store.
+     * @param key - The key to check
+     * @returns True if the key exists
+     */
+    has(key) {
+        return this.store.has(key);
+    }
+    /**
+     * Delete a key from the store.
+     * @param key - The key to delete
+     * @returns True if the key was deleted, false if it didn't exist
+     */
+    delete(key) {
+        return this.store.delete(key);
+    }
+    /**
+     * Get all keys in the store.
+     * @returns Array of all keys
+     */
+    keys() {
+        return Array.from(this.store.keys());
+    }
+    /**
+     * Get the number of entries in the store.
+     * @returns The number of entries
+     */
+    get size() {
+        return this.store.size;
+    }
+    /**
+     * Get all entries as a plain object.
+     * @returns Object with all key-value pairs
+     */
+    toObject() {
+        const obj = {};
+        for (const [key, value] of this.store) {
+            obj[key] = value;
+        }
+        return obj;
+    }
+    /**
+     * Clear all entries from the store.
+     */
+    clear() {
+        this.store.clear();
+    }
+    /**
+     * Create a clone of this context store.
+     * Note: This performs a shallow clone of values.
+     * @returns A new ContextStore with the same entries
+     */
+    clone() {
+        return new ContextStore(this.toObject());
+    }
+}
+exports.ContextStore = ContextStore;
+//# sourceMappingURL=ContextStore.js.map

package/dist/graph/context/ContextTools.d.ts

@@ -0,0 +1,52 @@
+import { Tool } from "../../tools/Tool";
+import { ContextStore } from "./ContextStore";
+/**
+ * Create a tool for agents to read from shared context.
+ *
+ * @param store - The ContextStore to read from
+ * @returns A Tool that retrieves values from the context store
+ *
+ * @example
+ * ```typescript
+ * const store = new ContextStore();
+ * const getTool = createContextGetTool(store);
+ * agent.addTools([getTool]);
+ * ```
+ */
+export declare function createContextGetTool(store: ContextStore): Tool<string>;
+/**
+ * Create a tool for agents to write to shared context.
+ *
+ * @param store - The ContextStore to write to
+ * @returns A Tool that stores values in the context store
+ *
+ * @example
+ * ```typescript
+ * const store = new ContextStore();
+ * const setTool = createContextSetTool(store);
+ * agent.addTools([setTool]);
+ * ```
+ */
+export declare function createContextSetTool(store: ContextStore): Tool<string>;
+/**
+ * Create a tool for agents to list available context keys.
+ *
+ * @param store - The ContextStore to list keys from
+ * @returns A Tool that lists all keys in the context store
+ *
+ * @example
+ * ```typescript
+ * const store = new ContextStore();
+ * const listTool = createContextListTool(store);
+ * agent.addTools([listTool]);
+ * ```
+ */
+export declare function createContextListTool(store: ContextStore): Tool<string>;
+/**
+ * Create a tool for agents to delete a key from context.
+ *
+ * @param store - The ContextStore to delete from
+ * @returns A Tool that deletes keys from the context store
+ */
+export declare function createContextDeleteTool(store: ContextStore): Tool<string>;
+//# sourceMappingURL=ContextTools.d.ts.map

package/dist/graph/context/ContextTools.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContextGetTool = createContextGetTool;
+exports.createContextSetTool = createContextSetTool;
+exports.createContextListTool = createContextListTool;
+exports.createContextDeleteTool = createContextDeleteTool;
+const Tool_1 = require("../../tools/Tool");
+/**
+ * Create a tool for agents to read from shared context.
+ *
+ * @param store - The ContextStore to read from
+ * @returns A Tool that retrieves values from the context store
+ *
+ * @example
+ * ```typescript
+ * const store = new ContextStore();
+ * const getTool = createContextGetTool(store);
+ * agent.addTools([getTool]);
+ * ```
+ */
+function createContextGetTool(store) {
+    return new Tool_1.Tool({
+        name: "context_get",
+        description: "Get a value from shared context by its descriptive key. Use list_context_keys first to see available keys.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                key: {
+                    type: "string",
+                    description: "The descriptive key to retrieve",
+                },
+            },
+            required: ["key"],
+        },
+        execute: async (input) => {
+            const value = store.get(input.key);
+            if (value === undefined) {
+                return JSON.stringify({
+                    error: `Key "${input.key}" not found`,
+                    availableKeys: store.keys(),
+                });
+            }
+            return JSON.stringify({ key: input.key, value });
+        },
+    });
+}
+/**
+ * Create a tool for agents to write to shared context.
+ *
+ * @param store - The ContextStore to write to
+ * @returns A Tool that stores values in the context store
+ *
+ * @example
+ * ```typescript
+ * const store = new ContextStore();
+ * const setTool = createContextSetTool(store);
+ * agent.addTools([setTool]);
+ * ```
+ */
+function createContextSetTool(store) {
+    return new Tool_1.Tool({
+        name: "context_set",
+        description: 'Store a value in shared context with a descriptive key. Use clear, descriptive keys like "research_findings", "user_preferences", "analysis_results".',
+        inputSchema: {
+            type: "object",
+            properties: {
+                key: {
+                    type: "string",
+                    description: "A descriptive key for this value",
+                },
+                value: {
+                    type: "string",
+                    description: "The value to store (JSON string for complex data)",
+                },
+            },
+            required: ["key", "value"],
+        },
+        execute: async (input) => {
+            // Try to parse JSON, otherwise store as string
+            let parsedValue = input.value;
+            try {
+                parsedValue = JSON.parse(input.value);
+            }
+            catch {
+                // Keep as string if not valid JSON
+            }
+            store.set(input.key, parsedValue);
+            return JSON.stringify({ success: true, key: input.key });
+        },
+    });
+}
+/**
+ * Create a tool for agents to list available context keys.
+ *
+ * @param store - The ContextStore to list keys from
+ * @returns A Tool that lists all keys in the context store
+ *
+ * @example
+ * ```typescript
+ * const store = new ContextStore();
+ * const listTool = createContextListTool(store);
+ * agent.addTools([listTool]);
+ * ```
+ */
+function createContextListTool(store) {
+    return new Tool_1.Tool({
+        name: "list_context_keys",
+        description: "List all available keys in the shared context.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        execute: async () => {
+            return JSON.stringify({ keys: store.keys() });
+        },
+    });
+}
+/**
+ * Create a tool for agents to delete a key from context.
+ *
+ * @param store - The ContextStore to delete from
+ * @returns A Tool that deletes keys from the context store
+ */
+function createContextDeleteTool(store) {
+    return new Tool_1.Tool({
+        name: "context_delete",
+        description: "Delete a key from the shared context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                key: {
+                    type: "string",
+                    description: "The key to delete",
+                },
+            },
+            required: ["key"],
+        },
+        execute: async (input) => {
+            const existed = store.delete(input.key);
+            return JSON.stringify({
+                success: true,
+                deleted: existed,
+                key: input.key,
+            });
+        },
+    });
+}
+//# sourceMappingURL=ContextTools.js.map

package/dist/graph/context/index.d.ts

@@ -0,0 +1,3 @@
+export { ContextStore } from "./ContextStore";
+export { createContextGetTool, createContextSetTool, createContextListTool, createContextDeleteTool, } from "./ContextTools";
+//# sourceMappingURL=index.d.ts.map

package/dist/graph/context/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContextDeleteTool = exports.createContextListTool = exports.createContextSetTool = exports.createContextGetTool = exports.ContextStore = void 0;
+var ContextStore_1 = require("./ContextStore");
+Object.defineProperty(exports, "ContextStore", { enumerable: true, get: function () { return ContextStore_1.ContextStore; } });
+var ContextTools_1 = require("./ContextTools");
+Object.defineProperty(exports, "createContextGetTool", { enumerable: true, get: function () { return ContextTools_1.createContextGetTool; } });
+Object.defineProperty(exports, "createContextSetTool", { enumerable: true, get: function () { return ContextTools_1.createContextSetTool; } });
+Object.defineProperty(exports, "createContextListTool", { enumerable: true, get: function () { return ContextTools_1.createContextListTool; } });
+Object.defineProperty(exports, "createContextDeleteTool", { enumerable: true, get: function () { return ContextTools_1.createContextDeleteTool; } });
+//# sourceMappingURL=index.js.map

package/dist/graph/planning/PlanExecutor.d.ts

@@ -0,0 +1,172 @@
+import { BaseAgent } from "../../agents/BaseAgent";
+import { BaseExecutor, GraphNode } from "../BaseExecutor";
+import { PlanStore } from "./PlanStore";
+import { PlanStep } from "./types";
+/**
+ * Options for PlanExecutor
+ */
+export interface PlanExecutorOptions {
+    /**
+     * Maximum number of steps to execute.
+     * @default 50
+     */
+    maxSteps?: number;
+    /**
+     * Maximum number of steps to execute concurrently.
+     * Set to 1 for sequential execution (default).
+     * Set to higher values to execute independent steps in parallel.
+     * @default 1
+     */
+    concurrency?: number;
+    /**
+     * Whether to stop execution when a step fails.
+     * @default true
+     */
+    stopOnFailure?: boolean;
+    /**
+     * Callback invoked when planning phase completes.
+     */
+    onPlanCreated?: (goal: string, steps: PlanStep[]) => void;
+    /**
+     * Callback invoked before each step starts.
+     */
+    onStepStart?: (step: PlanStep, stepNumber: number, totalSteps: number) => void;
+    /**
+     * Callback invoked after each step completes.
+     */
+    onStepComplete?: (step: PlanStep, result: string, stepNumber: number) => void;
+    /**
+     * Callback invoked when a step fails.
+     */
+    onStepFailed?: (step: PlanStep, error: Error, stepNumber: number) => void;
+}
+/**
+ * Result of a plan execution.
+ */
+export interface PlanExecutionResult {
+    success: boolean;
+    goal: string;
+    totalSteps: number;
+    completedSteps: number;
+    failedSteps: number;
+    summary: string;
+    /**
+     * Clean, consolidated output for chaining to next graph node.
+     * Contains a rollup of all step results in a format ready for downstream processing.
+     */
+    finalOutput: string;
+    /**
+     * Detailed results for each step (useful for debugging/inspection).
+     */
+    stepResults: Array<{
+        step: PlanStep;
+        result?: string;
+        error?: string;
+    }>;
+}
+/**
+ * Orchestrates plan-based execution with clear separation of concerns:
+ * 1. Planning Phase: Uses a planning agent to create a plan
+ * 2. Execution Phase: Assigns workers (agents or graph nodes) to execute each step
+ * 3. Completion: Compiles results and returns summary
+ *
+ * The PlanExecutor acts as the orchestrator, tracking progress and delegating
+ * work to specialized workers. Planning and execution are separate phases.
+ *
+ * @example
+ * ```typescript
+ * const planStore = AgentGraph.createPlanStore();
+ * const contextStore = AgentGraph.createContextStore();
+ *
+ * // Planning agent creates the plan
+ * const planner = new ClaudeAgent({
+ *   tools: AgentGraph.createPlanningTools(planStore),
+ *   description: 'You are a planning agent. Create a detailed plan with clear steps.',
+ * });
+ *
+ * // Worker agent executes individual steps
+ * const worker = new ClaudeAgent({
+ *   tools: AgentGraph.createContextTools(contextStore),
+ *   description: 'You execute a single step. Store results in context.',
+ * });
+ *
+ * const executor = new PlanExecutor(planStore, planner, worker, {
+ *   onStepComplete: (step, result, num) => {
+ *     console.log(`Completed step ${num}: ${step.description}`);
+ *   },
+ * });
+ *
+ * const result = await executor.execute('Research and summarize quantum computing');
+ * ```
+ */
+export declare class PlanExecutor extends BaseExecutor<string, string> {
+    private planStore;
+    private planningAgent;
+    private worker;
+    private lastResult?;
+    private options;
+    /**
+     * Create a new PlanExecutor.
+     *
+     * @param planStore - The plan store to track plan state
+     * @param planningAgent - Agent responsible for creating the plan
+     * @param worker - Agent or GraphNode that executes individual steps
+     * @param options - Configuration options
+     */
+    constructor(planStore: PlanStore, planningAgent: BaseAgent, worker: GraphNode<string, string> | BaseAgent, options?: PlanExecutorOptions);
+    /**
+     * Execute the plan:
+     * 1. Planning Phase: Ask planning agent to create a plan
+     * 2. Execution Phase: Execute each step with the worker
+     * 3. Completion: Return finalOutput (for chaining)
+     *
+     * Returns the finalOutput string for easy chaining in pipelines.
+     * Use getLastResult() to access the full PlanExecutionResult with details.
+     */
+    execute(input: string): Promise<string>;
+    /**
+     * Get the detailed result from the last execution.
+     * Contains full plan details, step results, and metadata.
+     */
+    getLastResult(): PlanExecutionResult | undefined;
+    /**
+     * Phase 1: Planning
+     * Instructs the planning agent to create a plan based on the task.
+     */
+    private planningPhase;
+    /**
+     * Phase 2: Execution
+     * Executes each step in the plan using the worker.
+     */
+    private executionPhase;
+    /**
+     * Create a prompt for the planning agent.
+     */
+    private createPlanningPrompt;
+    /**
+     * Create input for a step execution.
+     */
+    private createStepInput;
+    /**
+     * Compile the final result from step results.
+     */
+    private compileResult;
+    /**
+     * Create a clean, consolidated output from all step results.
+     * This output is designed for chaining to the next graph node.
+     */
+    private createFinalOutput;
+    /**
+     * Check if a worker is a BaseAgent.
+     */
+    private isAgent;
+    /**
+     * Extract token usage from an agent if available.
+     */
+    private extractTokenUsage;
+    /**
+     * Get the plan store.
+     */
+    getPlanStore(): PlanStore;
+}
+//# sourceMappingURL=PlanExecutor.d.ts.map