groundswell 0.0.1 → 0.0.3

package/dist/core/workflow-context.js

@@ -0,0 +1,263 @@
+/**
+ * WorkflowContextImpl - Implementation of functional workflow context
+ *
+ * Provides step(), spawnWorkflow(), and automatic context propagation
+ * for agents and prompts executed within workflows.
+ */
+import { EventTreeHandleImpl } from './event-tree.js';
+import { runInContext, } from './context.js';
+import { generateId } from '../utils/id.js';
+import { ReflectionManager } from '../reflection/reflection.js';
+import { createReflectionConfig } from '../types/index.js';
+import { getObservedState } from '../decorators/observed-state.js';
+/**
+ * WorkflowContext implementation
+ */
+export class WorkflowContextImpl {
+    workflowId;
+    parentWorkflowId;
+    eventTree;
+    reflection;
+    workflow;
+    eventTreeImpl;
+    reflectionManager;
+    constructor(workflow, parentWorkflowId, reflectionConfig) {
+        this.workflowId = workflow.id;
+        this.parentWorkflowId = parentWorkflowId;
+        this.workflow = workflow;
+        // Create event tree handle
+        this.eventTreeImpl = new EventTreeHandleImpl(workflow.node);
+        this.eventTree = this.eventTreeImpl;
+        // Create reflection manager with config
+        const config = createReflectionConfig(reflectionConfig);
+        this.reflectionManager = new ReflectionManager(config);
+        this.reflectionManager.setEventEmitter((event) => this.workflow.emitEvent(event));
+        this.reflection = this.reflectionManager;
+    }
+    /**
+     * Execute a named step with automatic context propagation and reflection support
+     */
+    async step(name, fn) {
+        const maxAttempts = this.reflectionManager.isEnabled()
+            ? this.reflectionManager.getMaxAttempts()
+            : 1;
+        let lastError = null;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const startTime = Date.now();
+            // Create step node
+            const stepNode = {
+                id: generateId(),
+                name: attempt > 1 ? `${name} (retry ${attempt - 1})` : name,
+                parent: this.workflow.node,
+                children: [],
+                status: 'running',
+                logs: [],
+                events: [],
+                stateSnapshot: null,
+            };
+            // Attach to parent
+            this.workflow.node.children.push(stepNode);
+            // Emit step start
+            this.workflow.emitEvent({
+                type: 'stepStart',
+                node: stepNode,
+                step: name,
+            });
+            // Create execution context for this step
+            const executionContext = {
+                workflowNode: stepNode,
+                emitEvent: (event) => {
+                    stepNode.events.push(event);
+                    this.workflow.emitEvent(event);
+                },
+                workflowId: this.workflowId,
+                parentWorkflowId: this.parentWorkflowId,
+            };
+            try {
+                // Execute function in context
+                const result = await runInContext(executionContext, fn);
+                // Update step node status
+                stepNode.status = 'completed';
+                // Emit step end
+                const duration = Date.now() - startTime;
+                this.workflow.emitEvent({
+                    type: 'stepEnd',
+                    node: stepNode,
+                    step: name,
+                    duration,
+                });
+                // Rebuild event tree
+                this.eventTreeImpl.rebuild(this.workflow.node);
+                // If we succeeded after a reflection, mark it as successful
+                if (attempt > 1) {
+                    this.reflectionManager.markLastReflectionSuccessful();
+                }
+                return result;
+            }
+            catch (error) {
+                lastError = error;
+                // Update step node status
+                stepNode.status = 'failed';
+                // Emit error event
+                this.workflow.emitEvent({
+                    type: 'error',
+                    node: stepNode,
+                    error: {
+                        message: error instanceof Error ? error.message : 'Unknown error',
+                        original: error,
+                        workflowId: this.workflowId,
+                        stack: error instanceof Error ? error.stack : undefined,
+                        state: getObservedState(this.workflow),
+                        logs: [...this.workflow.node.logs],
+                    },
+                });
+                // Rebuild event tree
+                this.eventTreeImpl.rebuild(this.workflow.node);
+                // Check if we should try reflection
+                if (!this.reflectionManager.isEnabled() || attempt === maxAttempts) {
+                    throw error;
+                }
+                // Try reflection
+                const reflectionContext = {
+                    level: 'workflow',
+                    failedNode: stepNode,
+                    error: lastError,
+                    attemptNumber: attempt,
+                    previousAttempts: this.reflectionManager.getReflectionHistory(),
+                };
+                const reflectionResult = await this.reflectionManager.reflect(reflectionContext);
+                if (!reflectionResult.shouldRetry) {
+                    throw lastError;
+                }
+                // Continue to next iteration for retry
+            }
+        }
+        throw lastError ?? new Error('Max reflection attempts exceeded');
+    }
+    /**
+     * Spawn a child workflow
+     */
+    async spawnWorkflow(workflow) {
+        // If workflow has attachChild-like capability, use it
+        if ('node' in workflow && workflow.node) {
+            // Set parent reference
+            workflow.node.parent = this.workflow.node;
+            // Attach child node
+            this.workflow.node.children.push(workflow.node);
+            // Emit child attached event
+            this.workflow.emitEvent({
+                type: 'childAttached',
+                parentId: this.workflowId,
+                child: workflow.node,
+            });
+        }
+        // Run the child workflow
+        const result = await workflow.run();
+        // Rebuild event tree
+        this.eventTreeImpl.rebuild(this.workflow.node);
+        return result;
+    }
+    /**
+     * Replace the last prompt result with a new one (context revision)
+     * The previous prompt node is marked as 'revised' and the new result is attached as sibling
+     */
+    async replaceLastPromptResult(newPrompt, agent) {
+        // Find the last completed prompt node in the tree
+        const children = this.workflow.node.children;
+        let lastPromptNodeIndex = -1;
+        for (let i = children.length - 1; i >= 0; i--) {
+            const child = children[i];
+            if (child.status === 'completed') {
+                lastPromptNodeIndex = i;
+                break;
+            }
+        }
+        // Create a revision node to mark the replacement
+        const revisionNode = {
+            id: generateId(),
+            name: `revision:${newPrompt.id}`,
+            parent: this.workflow.node,
+            children: [],
+            status: 'running',
+            logs: [],
+            events: [],
+            stateSnapshot: null,
+        };
+        // If we found a previous node, mark it as revised
+        if (lastPromptNodeIndex >= 0) {
+            const previousNode = children[lastPromptNodeIndex];
+            // Mark as revised by adding a special status flag in logs
+            previousNode.logs.push({
+                id: generateId(),
+                workflowId: this.workflowId,
+                level: 'info',
+                message: `Revised by ${revisionNode.id}`,
+                timestamp: Date.now(),
+            });
+        }
+        // Attach revision node as sibling (at same level)
+        this.workflow.node.children.push(revisionNode);
+        // Emit prompt revision event
+        this.workflow.emitEvent({
+            type: 'stepStart',
+            node: revisionNode,
+            step: `revision:${newPrompt.id}`,
+        });
+        // Create execution context for this revision
+        const executionContext = {
+            workflowNode: revisionNode,
+            emitEvent: (event) => {
+                revisionNode.events.push(event);
+                this.workflow.emitEvent(event);
+            },
+            workflowId: this.workflowId,
+            parentWorkflowId: this.parentWorkflowId,
+        };
+        try {
+            // Execute the new prompt in context
+            const result = await runInContext(executionContext, () => agent.prompt(newPrompt));
+            // Update revision node status
+            revisionNode.status = 'completed';
+            // Emit completion event
+            this.workflow.emitEvent({
+                type: 'stepEnd',
+                node: revisionNode,
+                step: `revision:${newPrompt.id}`,
+                duration: 0, // Could track actual duration if needed
+            });
+            // Rebuild event tree
+            this.eventTreeImpl.rebuild(this.workflow.node);
+            return result;
+        }
+        catch (error) {
+            // Update revision node status
+            revisionNode.status = 'failed';
+            // Emit error event
+            this.workflow.emitEvent({
+                type: 'error',
+                node: revisionNode,
+                error: {
+                    message: error instanceof Error ? error.message : 'Unknown error',
+                    original: error,
+                    workflowId: this.workflowId,
+                    stack: error instanceof Error ? error.stack : undefined,
+                    state: getObservedState(this.workflow),
+                    logs: [...this.workflow.node.logs],
+                },
+            });
+            // Rebuild event tree
+            this.eventTreeImpl.rebuild(this.workflow.node);
+            throw error;
+        }
+    }
+}
+/**
+ * Create a WorkflowContext for a workflow
+ * @param workflow The workflow object
+ * @param parentWorkflowId Optional parent workflow ID
+ * @param reflectionConfig Optional reflection configuration
+ */
+export function createWorkflowContext(workflow, parentWorkflowId, reflectionConfig) {
+    return new WorkflowContextImpl(workflow, parentWorkflowId, reflectionConfig);
+}
+//# sourceMappingURL=workflow-context.js.map

package/dist/core/workflow-context.js.map

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

package/dist/core/workflow.d.ts

@@ -0,0 +1,241 @@
+import type { WorkflowNode, WorkflowStatus, WorkflowEvent, WorkflowObserver } from '../types/index.js';
+import type { WorkflowContext, WorkflowConfig, WorkflowResult } from '../types/workflow-context.js';
+import { WorkflowLogger } from './logger.js';
+/**
+ * Executor function type for functional workflows
+ */
+export type WorkflowExecutor<T = unknown> = (ctx: WorkflowContext) => Promise<T>;
+/**
+ * Base class for all workflows
+ * Supports both class-based (subclass with run()) and functional (executor) patterns
+ *
+ * @example Class-based pattern:
+ * ```ts
+ * class MyWorkflow extends Workflow {
+ *   async run() {
+ *     this.setStatus('running');
+ *     // workflow logic
+ *     this.setStatus('completed');
+ *   }
+ * }
+ * ```
+ *
+ * @example Functional pattern:
+ * ```ts
+ * const workflow = new Workflow({ name: 'MyWorkflow' }, async (ctx) => {
+ *   await ctx.step('step1', async () => {
+ *     // step logic
+ *   });
+ * });
+ * await workflow.run();
+ * ```
+ */
+export declare class Workflow<T = unknown> {
+    /** Unique identifier for this workflow instance */
+    readonly id: string;
+    /** Parent workflow (null for root workflows) */
+    parent: Workflow | null;
+    /** Child workflows */
+    children: Workflow[];
+    /** Current execution status */
+    status: WorkflowStatus;
+    /** Logger instance for this workflow */
+    protected readonly logger: WorkflowLogger;
+    /** The node representation of this workflow */
+    readonly node: WorkflowNode;
+    /** Observers (only populated on root workflow) */
+    private observers;
+    /** Optional executor function for functional workflows */
+    private executor?;
+    /** Workflow configuration */
+    private config;
+    /**
+     * Create a new workflow instance
+     *
+     * @overload Class-based pattern
+     * @param name Human-readable name (defaults to class name)
+     * @param parent Optional parent workflow
+     *
+     * @overload Functional pattern
+     * @param config Workflow configuration
+     * @param executor Executor function
+     */
+    constructor(name?: string | WorkflowConfig, parentOrExecutor?: Workflow | WorkflowExecutor<T>);
+    /**
+     * Get observers from the root workflow
+     * Traverses up the tree to find the root
+     * Uses cycle detection to prevent infinite loops from circular parent-child relationships
+     */
+    private getRootObservers;
+    /**
+     * Check if this workflow is a descendant of the given ancestor workflow.
+     *
+     * Traverses the parent chain upward looking for the ancestor reference.
+     * Uses a visited Set to detect cycles during traversal. This method provides
+     * a convenient way to check workflow hierarchy relationships without manually
+     * traversing the parent chain.
+     *
+     * @warning This method reveals workflow hierarchy information. If your
+     * application exposes workflows via an API, ensure you implement proper
+     * access control to prevent unauthorized topology discovery. Note that
+     * the `parent` and `children` properties are already public, so this
+     * method does not expose any new information beyond what is currently
+     * accessible.
+     *
+     * **Time Complexity**: O(d) where d is the depth of the hierarchy
+     * **Space Complexity**: O(d) for the visited Set in worst case (cycle detection)
+     *
+     * @example Check if a workflow belongs to a specific hierarchy
+     * ```typescript
+     * const root = new Workflow('root');
+     * const child = new Workflow('child', { parent: root });
+     *
+     * if (child.isDescendantOf(root)) {
+     *   console.log('Child is in root hierarchy');
+     * }
+     * ```
+     *
+     * @example Validate before attaching to prevent circular references
+     * ```typescript
+     * if (!newChild.isDescendantOf(parent)) {
+     *   parent.attachChild(newChild);
+     * } else {
+     *   throw new Error('Would create circular reference');
+     * }
+     * ```
+     *
+     * @example Check for ancestor relationship in conditional logic
+     * ```typescript
+     * const isInProductionBranch = workflow.isDescendantOf(productionRoot);
+     * if (isInProductionBranch) {
+     *   // Apply production-specific logic
+     * }
+     * ```
+     *
+     * @param ancestor - The potential ancestor workflow to check
+     * @returns true if ancestor is found in parent chain, false otherwise
+     * @throws {Error} If a cycle is detected during traversal (indicates corrupted tree structure)
+     */
+    isDescendantOf(ancestor: Workflow): boolean;
+    /**
+     * Get the root workflow
+     * Uses cycle detection to prevent infinite loops from circular parent-child relationships
+     */
+    protected getRoot(): Workflow;
+    /**
+     * Add an observer to this workflow (must be root)
+     * @throws Error if called on non-root workflow
+     */
+    addObserver(observer: WorkflowObserver): void;
+    /**
+     * Remove an observer from this workflow
+     */
+    removeObserver(observer: WorkflowObserver): void;
+    /**
+     * Attach a child workflow to this parent workflow.
+     *
+     * Validates that the child can be attached by checking:
+     * 1. Child is not already attached to this parent workflow
+     * 2. Child does not have a different parent (enforces single-parent invariant)
+     * 3. Child is not an ancestor of this parent (prevents circular references)
+     *
+     * **Structural Changes:**
+     * - Adds child to this.children array (workflow tree)
+     * - Adds child.node to this.node.children array (node tree)
+     * - Sets child.parent = this (workflow tree)
+     * - Sets child.node.parent = this.node (node tree)
+     * - Emits childAttached event to notify observers
+     *
+     * **Invariants Maintained:**
+     * - Single-parent rule: A workflow can only have one parent
+     * - 1:1 tree mirror: workflow tree and node tree stay synchronized
+     * - No cycles: A workflow cannot be its own ancestor
+     *
+     * **Cycle Detection:**
+     * - Uses isDescendantOf() helper with Set-based cycle detection
+     * - Throws immediately if circular reference would be created
+     *
+     * @param child - The child workflow to attach
+     * @throws {Error} If the child is already attached to this workflow
+     * @throws {Error} If the child already has a different parent (use detachChild() first for reparenting)
+     * @throws {Error} If the child is an ancestor of this parent (would create circular reference)
+     *
+     * @example
+     * ```ts
+     * const parent = new Workflow('Parent');
+     * const child = new Workflow('Child');
+     * parent.attachChild(child);
+     * // child.parent === parent
+     * // parent.children.includes(child) === true
+     * ```
+     *
+     * @example Reparenting workflow
+     * ```ts
+     * const parent1 = new Workflow('Parent1');
+     * const parent2 = new Workflow('Parent2');
+     * const child = new Workflow('Child', parent1); // Attached to parent1
+     *
+     * // Later, move child to parent2
+     * parent1.detachChild(child);
+     * parent2.attachChild(child);
+     * // child.parent === parent2
+     * ```
+     *
+     * @see detachChild - For detaching children (enables reparenting)
+     * @see isDescendantOf - Private helper for circular reference detection
+     */
+    attachChild(child: Workflow): void;
+    /**
+     * Detach a child workflow from this parent workflow.
+     *
+     * Removes the child from both the workflow tree (this.children) and
+     * the node tree (this.node.children), clears the child's parent reference,
+     * and emits a childDetached event to notify observers.
+     *
+     * This enables reparenting workflows: oldParent.detachChild(child); newParent.attachChild(child);
+     *
+     * @param child - The child workflow to detach
+     * @throws {Error} If the child is not attached to this parent workflow
+     *
+     * @example
+     * ```ts
+     * const parent = new Workflow('Parent');
+     * const child = new Workflow('Child', parent);
+     *
+     * // Later, reparent to a different parent
+     * parent.detachChild(child);
+     * newParent.attachChild(child);
+     * ```
+     */
+    detachChild(child: Workflow): void;
+    /**
+     * Emit an event to all root observers
+     */
+    emitEvent(event: WorkflowEvent): void;
+    /**
+     * Capture and emit a state snapshot
+     */
+    snapshotState(): void;
+    /**
+     * Update workflow status and sync with node
+     */
+    setStatus(status: WorkflowStatus): void;
+    /**
+     * Get the node representation of this workflow
+     */
+    getNode(): WorkflowNode;
+    /**
+     * Run the workflow
+     *
+     * For functional workflows (created with executor), runs the executor function.
+     * For class-based workflows (subclasses), this should be overridden.
+     *
+     * @returns Workflow result
+     */
+    run(..._args: unknown[]): Promise<T | WorkflowResult<T>>;
+    /**
+     * Run a functional workflow with context
+     */
+    private runFunctional;
+}
+//# sourceMappingURL=workflow.d.ts.map

package/dist/core/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/core/workflow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEpG,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI7C;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,QAAQ,CAAC,CAAC,GAAG,OAAO;IAC/B,mDAAmD;IACnD,SAAgB,EAAE,EAAE,MAAM,CAAC;IAE3B,gDAAgD;IACzC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAQ;IAEtC,sBAAsB;IACf,QAAQ,EAAE,QAAQ,EAAE,CAAM;IAEjC,+BAA+B;IACxB,MAAM,EAAE,cAAc,CAAU;IAEvC,wCAAwC;IACxC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAE1C,+CAA+C;IAC/C,SAAgB,IAAI,EAAE,YAAY,CAAC;IAEnC,kDAAkD;IAClD,OAAO,CAAC,SAAS,CAA0B;IAE3C,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,CAAsB;IAEvC,6BAA6B;IAC7B,OAAO,CAAC,MAAM,CAAiB;IAE/B;;;;;;;;;;OAUG;gBACS,IAAI,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,gBAAgB,CAAC,EAAE,QAAQ,GAAG,gBAAgB,CAAC,CAAC,CAAC;IA+C7F;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACI,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO;IAoBlD;;;OAGG;IACH,SAAS,CAAC,OAAO,IAAI,QAAQ;IAiB7B;;;OAGG;IACI,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAOpD;;OAEG;IACI,cAAc,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAOvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoDG;IACI,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAyCzC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACI,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IA+BzC;;OAEG;IACI,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IAkB5C;;OAEG;IACI,aAAa,IAAI,IAAI;IAwB5B;;OAEG;IACI,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAM9C;;OAEG;IACI,OAAO,IAAI,YAAY;IAI9B;;;;;;;OAOG;IACU,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;IAWrE;;OAEG;YACW,aAAa;CA4C5B"}