groundswell 0.0.1 → 0.0.3

package/dist/types/logging.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Log severity levels
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * A single log entry in the workflow
+ */
+export interface LogEntry {
+    /** Unique identifier for this log entry */
+    id: string;
+    /** ID of the workflow that created this log */
+    workflowId: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Severity level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** Optional structured data */
+    data?: unknown;
+    /** ID of parent log entry (for hierarchical logging) */
+    parentLogId?: string;
+}
+//# sourceMappingURL=logging.d.ts.map

package/dist/types/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../src/types/logging.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,kBAAkB;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB"}

package/dist/types/logging.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=logging.js.map

package/dist/types/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../../src/types/logging.ts"],"names":[],"mappings":""}

package/dist/types/observer.d.ts

@@ -0,0 +1,18 @@
+import type { LogEntry } from './logging.js';
+import type { WorkflowEvent } from './events.js';
+import type { WorkflowNode } from './workflow.js';
+/**
+ * Observer interface for subscribing to workflow events
+ * Observers attach to the root workflow and receive all events
+ */
+export interface WorkflowObserver {
+    /** Called when a log entry is created */
+    onLog(entry: LogEntry): void;
+    /** Called when any workflow event occurs */
+    onEvent(event: WorkflowEvent): void;
+    /** Called when a node's state is updated */
+    onStateUpdated(node: WorkflowNode): void;
+    /** Called when the tree structure changes */
+    onTreeChanged(root: WorkflowNode): void;
+}
+//# sourceMappingURL=observer.d.ts.map

package/dist/types/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../src/types/observer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,KAAK,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC7B,4CAA4C;IAC5C,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACpC,4CAA4C;IAC5C,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACzC,6CAA6C;IAC7C,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;CACzC"}

package/dist/types/observer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=observer.js.map

package/dist/types/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../src/types/observer.ts"],"names":[],"mappings":""}

package/dist/types/prompt.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Prompt configuration types
+ * Prompts are immutable definitions of what to send to an agent
+ */
+import type { z } from 'zod';
+import type { Tool, MCPServer, Skill, AgentHooks } from './sdk-primitives.js';
+/**
+ * Configuration for creating a Prompt instance
+ * @template T The expected response type (inferred from responseFormat)
+ */
+export interface PromptConfig<T> {
+    /** User message content */
+    user: string;
+    /** Structured data to inject into the prompt */
+    data?: Record<string, unknown>;
+    /** Zod schema defining the expected response format */
+    responseFormat: z.ZodType<T>;
+    /** Override system prompt (takes precedence over agent config) */
+    system?: string;
+    /** Override tools (takes precedence over agent config) */
+    tools?: Tool[];
+    /** Override MCPs (takes precedence over agent config) */
+    mcps?: MCPServer[];
+    /** Override skills (takes precedence over agent config) */
+    skills?: Skill[];
+    /** Override hooks (takes precedence over agent config) */
+    hooks?: AgentHooks;
+    /** Enable reflection specifically for this prompt */
+    enableReflection?: boolean;
+}
+//# sourceMappingURL=prompt.d.ts.map

package/dist/types/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/types/prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE9E;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IAEb,gDAAgD;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE/B,uDAAuD;IACvD,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAE7B,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAEf,yDAAyD;IACzD,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC;IAEnB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IAEjB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,UAAU,CAAC;IAEnB,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B"}

package/dist/types/prompt.js

@@ -0,0 +1,6 @@
+/**
+ * Prompt configuration types
+ * Prompts are immutable definitions of what to send to an agent
+ */
+export {};
+//# sourceMappingURL=prompt.js.map

package/dist/types/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/types/prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/types/reflection.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Reflection types - Interfaces for multi-level reflection and self-correction
+ *
+ * Reflection allows agents to analyze errors and retry with modified approaches.
+ * Supports workflow, agent, and prompt level reflection with configurable limits.
+ */
+import type { WorkflowNode } from './workflow.js';
+/**
+ * Configuration for reflection behavior
+ */
+export interface ReflectionConfig {
+    /** Whether reflection is enabled */
+    enabled: boolean;
+    /** Maximum number of reflection attempts (default: 3) */
+    maxAttempts: number;
+    /** Delay between retry attempts in milliseconds (default: 0) */
+    retryDelayMs?: number;
+}
+/**
+ * Context provided to the reflection process
+ */
+export interface ReflectionContext {
+    /** Level at which reflection is occurring */
+    level: 'workflow' | 'agent' | 'prompt';
+    /** The workflow node that failed */
+    failedNode: WorkflowNode;
+    /** The error that triggered reflection */
+    error: Error;
+    /** Current attempt number (1-indexed) */
+    attemptNumber: number;
+    /** History of previous reflection attempts */
+    previousAttempts: ReflectionEntry[];
+}
+/**
+ * Result from a reflection analysis
+ */
+export interface ReflectionResult {
+    /** Whether to retry the operation */
+    shouldRetry: boolean;
+    /** Revised prompt data for retry */
+    revisedPromptData?: Record<string, unknown>;
+    /** Revised system prompt for retry */
+    revisedSystemPrompt?: string;
+    /** Explanation of the reflection decision */
+    reason: string;
+}
+/**
+ * Record of a single reflection attempt
+ */
+export interface ReflectionEntry {
+    /** Timestamp when reflection occurred */
+    timestamp: number;
+    /** Level at which reflection occurred */
+    level: 'workflow' | 'agent' | 'prompt';
+    /** Reason for the reflection */
+    reason: string;
+    /** Original error that triggered reflection */
+    error: Error;
+    /** Resolution action taken */
+    resolution: 'retry' | 'skip' | 'abort';
+    /** Whether the retry was successful */
+    success: boolean;
+}
+/**
+ * Full ReflectionAPI interface for workflow contexts
+ */
+export interface ReflectionAPI {
+    /**
+     * Check if reflection is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Trigger a reflection on the current context
+     * @param reason Optional reason for the reflection
+     */
+    triggerReflection(reason?: string): Promise<void>;
+    /**
+     * Get the history of reflection attempts
+     */
+    getReflectionHistory(): ReflectionEntry[];
+    /**
+     * Perform reflection analysis on an error
+     * @param context The reflection context with error details
+     * @returns Result indicating whether to retry
+     */
+    reflect(context: ReflectionContext): Promise<ReflectionResult>;
+}
+/**
+ * Default reflection configuration
+ */
+export declare const DEFAULT_REFLECTION_CONFIG: ReflectionConfig;
+/**
+ * Create a reflection config with defaults
+ */
+export declare function createReflectionConfig(partial?: Partial<ReflectionConfig>): ReflectionConfig;
+//# sourceMappingURL=reflection.d.ts.map

package/dist/types/reflection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection.d.ts","sourceRoot":"","sources":["../../src/types/reflection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvC,oCAAoC;IACpC,UAAU,EAAE,YAAY,CAAC;IACzB,0CAA0C;IAC1C,KAAK,EAAE,KAAK,CAAC;IACb,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,gBAAgB,EAAE,eAAe,EAAE,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,WAAW,EAAE,OAAO,CAAC;IACrB,oCAAoC;IACpC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,sCAAsC;IACtC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,KAAK,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvC,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,KAAK,EAAE,KAAK,CAAC;IACb,8BAA8B;IAC9B,UAAU,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACvC,uCAAuC;IACvC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;;OAGG;IACH,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;OAEG;IACH,oBAAoB,IAAI,eAAe,EAAE,CAAC;IAE1C;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChE;AAED;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,gBAIvC,CAAC;AAEF;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAClC,gBAAgB,CAKlB"}

package/dist/types/reflection.js

@@ -0,0 +1,24 @@
+/**
+ * Reflection types - Interfaces for multi-level reflection and self-correction
+ *
+ * Reflection allows agents to analyze errors and retry with modified approaches.
+ * Supports workflow, agent, and prompt level reflection with configurable limits.
+ */
+/**
+ * Default reflection configuration
+ */
+export const DEFAULT_REFLECTION_CONFIG = {
+    enabled: false,
+    maxAttempts: 3,
+    retryDelayMs: 0,
+};
+/**
+ * Create a reflection config with defaults
+ */
+export function createReflectionConfig(partial) {
+    return {
+        ...DEFAULT_REFLECTION_CONFIG,
+        ...partial,
+    };
+}
+//# sourceMappingURL=reflection.js.map

package/dist/types/reflection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection.js","sourceRoot":"","sources":["../../src/types/reflection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA4FH;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAqB;IACzD,OAAO,EAAE,KAAK;IACd,WAAW,EAAE,CAAC;IACd,YAAY,EAAE,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAmC;IAEnC,OAAO;QACL,GAAG,yBAAyB;QAC5B,GAAG,OAAO;KACX,CAAC;AACJ,CAAC"}

package/dist/types/sdk-primitives.d.ts

@@ -0,0 +1,118 @@
+/**
+ * SDK primitive types that mirror Anthropic SDK structures
+ * These types pass through unchanged to the SDK
+ */
+/**
+ * Tool definition for Anthropic SDK
+ * Maps directly to Anthropic.Tool
+ */
+export interface Tool {
+    /** Tool name (must be unique within an agent) */
+    name: string;
+    /** Human-readable description of what the tool does */
+    description: string;
+    /** JSON Schema describing the tool's input parameters */
+    input_schema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Tool result returned from tool execution
+ */
+export interface ToolResult {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string | unknown;
+    is_error?: boolean;
+}
+/**
+ * MCP Server configuration
+ * Supports stdio and inprocess transports
+ */
+export interface MCPServer {
+    /** Server name for identification */
+    name: string;
+    /** Server version (optional) */
+    version?: string;
+    /** Transport type */
+    transport: 'stdio' | 'inprocess';
+    /** Command to run for stdio transport */
+    command?: string;
+    /** Arguments for the command */
+    args?: string[];
+    /** Tools provided by this MCP server */
+    tools?: Tool[];
+    /** Environment variables for the MCP process */
+    env?: Record<string, string>;
+}
+/**
+ * Skill definition
+ * Skills are loaded from directories containing SKILL.md
+ */
+export interface Skill {
+    /** Skill name for identification */
+    name: string;
+    /** Path to skill directory containing SKILL.md */
+    path: string;
+}
+/**
+ * Hook handler function type
+ */
+export type HookHandler<T = unknown> = (context: T) => Promise<void> | void;
+/**
+ * Pre-tool use hook context
+ */
+export interface PreToolUseContext {
+    toolName: string;
+    toolInput: unknown;
+    agentId: string;
+}
+/**
+ * Post-tool use hook context
+ */
+export interface PostToolUseContext {
+    toolName: string;
+    toolInput: unknown;
+    toolOutput: unknown;
+    agentId: string;
+    duration: number;
+}
+/**
+ * Session start hook context
+ */
+export interface SessionStartContext {
+    agentId: string;
+    agentName?: string;
+}
+/**
+ * Session end hook context
+ */
+export interface SessionEndContext {
+    agentId: string;
+    agentName?: string;
+    totalDuration: number;
+}
+/**
+ * Agent lifecycle hooks
+ * Maps to Anthropic SDK hook conventions
+ */
+export interface AgentHooks {
+    /** Called before each tool invocation */
+    preToolUse?: HookHandler<PreToolUseContext>[];
+    /** Called after each tool invocation */
+    postToolUse?: HookHandler<PostToolUseContext>[];
+    /** Called when agent session starts */
+    sessionStart?: HookHandler<SessionStartContext>[];
+    /** Called when agent session ends */
+    sessionEnd?: HookHandler<SessionEndContext>[];
+}
+/**
+ * Token usage information from API response
+ */
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+//# sourceMappingURL=sdk-primitives.d.ts.map

package/dist/types/sdk-primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-primitives.d.ts","sourceRoot":"","sources":["../../src/types/sdk-primitives.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,WAAW,IAAI;IACnB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,YAAY,EAAE;QACZ,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB;IACrB,SAAS,EAAE,OAAO,GAAG,WAAW,CAAC;IACjC,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,wCAAwC;IACxC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,KAAK;IACpB,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,UAAU,CAAC,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAC9C,wCAAwC;IACxC,WAAW,CAAC,EAAE,WAAW,CAAC,kBAAkB,CAAC,EAAE,CAAC;IAChD,uCAAuC;IACvC,YAAY,CAAC,EAAE,WAAW,CAAC,mBAAmB,CAAC,EAAE,CAAC;IAClD,qCAAqC;IACrC,UAAU,CAAC,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;CAC/C;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/types/sdk-primitives.js

@@ -0,0 +1,6 @@
+/**
+ * SDK primitive types that mirror Anthropic SDK structures
+ * These types pass through unchanged to the SDK
+ */
+export {};
+//# sourceMappingURL=sdk-primitives.js.map

package/dist/types/sdk-primitives.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-primitives.js","sourceRoot":"","sources":["../../src/types/sdk-primitives.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/{src/types/snapshot.ts → dist/types/snapshot.d.ts}

@@ -2,13 +2,13 @@
  * Serialized workflow state as key-value pairs
  */
 export type SerializedWorkflowState = Record<string, unknown>;
-
 /**
  * Metadata for observed state fields
  */
 export interface StateFieldMetadata {
-  /** If true, field is not included in snapshots */
-  hidden?: boolean;
-  /** If true, value is shown as '***' in snapshots */
-  redact?: boolean;
+    /** If true, field is not included in snapshots */
+    hidden?: boolean;
+    /** If true, value is shown as '***' in snapshots */
+    redact?: boolean;
 }
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/types/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../../src/types/snapshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}

package/dist/types/snapshot.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=snapshot.js.map

package/dist/types/snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.js","sourceRoot":"","sources":["../../src/types/snapshot.ts"],"names":[],"mappings":""}

package/dist/types/workflow-context.d.ts

@@ -0,0 +1,139 @@
+/**
+ * WorkflowContext - Interface for functional workflow execution
+ *
+ * Provides step(), spawnWorkflow(), and other methods for
+ * composing workflows in arbitrary JavaScript control flow.
+ */
+import type { WorkflowNode } from './workflow.js';
+import type { ReflectionAPI } from './reflection.js';
+export type { ReflectionAPI } from './reflection.js';
+/**
+ * Handle for querying the event tree
+ */
+export interface EventTreeHandle {
+    /** Root node of the event tree */
+    readonly root: EventNode;
+    /**
+     * Get a node by ID
+     * @param id Node ID to find
+     */
+    getNode(id: string): EventNode | undefined;
+    /**
+     * Get all children of a node
+     * @param id Parent node ID
+     */
+    getChildren(id: string): EventNode[];
+    /**
+     * Get all ancestors of a node (from node up to root)
+     * @param id Node ID
+     */
+    getAncestors(id: string): EventNode[];
+    /**
+     * Export tree as JSON
+     */
+    toJSON(): EventNode;
+}
+/**
+ * Event node in the queryable tree
+ */
+export interface EventNode {
+    id: string;
+    type: string;
+    timestamp: number;
+    name?: string;
+    payload?: unknown;
+    metrics?: EventMetrics;
+    parentId?: string;
+    children: EventNode[];
+}
+/**
+ * Metrics associated with an event node
+ */
+export interface EventMetrics {
+    duration?: number;
+    tokenUsage?: {
+        input: number;
+        output: number;
+    };
+    toolCalls?: number;
+}
+/**
+ * Agent interface for context revision (minimal to avoid circular deps)
+ */
+export interface AgentLike {
+    prompt<T>(prompt: PromptLike<T>): Promise<T>;
+}
+/**
+ * Prompt interface for context revision (minimal to avoid circular deps)
+ */
+export interface PromptLike<T> {
+    id: string;
+    buildUserMessage(): string;
+    validateResponse(data: unknown): T;
+}
+/**
+ * WorkflowContext - Available within functional workflow executor
+ */
+export interface WorkflowContext {
+    /** Unique ID of this workflow */
+    readonly workflowId: string;
+    /** Parent workflow ID if nested */
+    readonly parentWorkflowId?: string;
+    /**
+     * Execute a named step
+     * Can be called anywhere in JavaScript control flow (loops, conditionals, etc.)
+     *
+     * @param name Step name for logging and debugging
+     * @param fn Step function to execute
+     * @returns Result of the step function
+     */
+    step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Spawn a child workflow
+     * The child workflow is automatically attached to this workflow's tree
+     *
+     * @param workflow Workflow instance to spawn
+     * @returns Result of the child workflow
+     */
+    spawnWorkflow<T>(workflow: {
+        run(): Promise<T>;
+    }): Promise<T>;
+    /**
+     * 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
+     *
+     * @param newPrompt The new prompt to execute
+     * @param agent The agent to use for execution
+     * @returns Result of the new prompt
+     */
+    replaceLastPromptResult<T>(newPrompt: PromptLike<T>, agent: AgentLike): Promise<T>;
+    /**
+     * Access to the event tree for this workflow
+     */
+    readonly eventTree: EventTreeHandle;
+    /**
+     * Reflection API for error handling and retry logic
+     */
+    readonly reflection: ReflectionAPI;
+}
+/**
+ * Configuration for creating a functional workflow
+ */
+export interface WorkflowConfig {
+    /** Human-readable workflow name */
+    name?: string;
+    /** Enable reflection for this workflow */
+    enableReflection?: boolean;
+}
+/**
+ * Result from workflow execution
+ */
+export interface WorkflowResult<T = unknown> {
+    /** The result value */
+    data: T;
+    /** The workflow node */
+    node: WorkflowNode;
+    /** Total duration in milliseconds */
+    duration: number;
+}
+//# sourceMappingURL=workflow-context.d.ts.map

package/dist/types/workflow-context.d.ts.map

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

package/dist/types/workflow-context.js

@@ -0,0 +1,8 @@
+/**
+ * WorkflowContext - Interface for functional workflow execution
+ *
+ * Provides step(), spawnWorkflow(), and other methods for
+ * composing workflows in arbitrary JavaScript control flow.
+ */
+export {};
+//# sourceMappingURL=workflow-context.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-context.js","sourceRoot":"","sources":["../../src/types/workflow-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/types/workflow.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Workflow status representing the current execution state
+ */
+export type WorkflowStatus = 'idle' | 'running' | 'completed' | 'failed' | 'cancelled';
+import type { LogEntry } from './logging.js';
+import type { WorkflowEvent } from './events.js';
+import type { SerializedWorkflowState } from './snapshot.js';
+/**
+ * Represents a node in the workflow execution tree
+ * This is the data structure, not the Workflow class
+ */
+export interface WorkflowNode {
+    /** Unique identifier for this workflow instance */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Parent node reference (null for root) */
+    parent: WorkflowNode | null;
+    /** Child workflow nodes */
+    children: WorkflowNode[];
+    /** Current execution status */
+    status: WorkflowStatus;
+    /** Log entries for this node */
+    logs: LogEntry[];
+    /** Events emitted by this node */
+    events: WorkflowEvent[];
+    /** Optional serialized state snapshot */
+    stateSnapshot: SerializedWorkflowState | null;
+}
+//# sourceMappingURL=workflow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/types/workflow.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,SAAS,GACT,WAAW,GACX,QAAQ,GACR,WAAW,CAAC;AAGhB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,2BAA2B;IAC3B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,+BAA+B;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,gCAAgC;IAChC,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,kCAAkC;IAClC,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,yCAAyC;IACzC,aAAa,EAAE,uBAAuB,GAAG,IAAI,CAAC;CAC/C"}

package/dist/types/workflow.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workflow.js.map

package/dist/types/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["../../src/types/workflow.ts"],"names":[],"mappings":""}

package/dist/utils/id.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Generate a unique identifier
+ * Uses crypto.randomUUID if available, falls back to timestamp + random
+ */
+export declare function generateId(): string;
+//# sourceMappingURL=id.d.ts.map

package/dist/utils/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAMnC"}

package/dist/utils/id.js

@@ -0,0 +1,12 @@
+/**
+ * Generate a unique identifier
+ * Uses crypto.randomUUID if available, falls back to timestamp + random
+ */
+export function generateId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return crypto.randomUUID();
+    }
+    // Fallback for environments without crypto.randomUUID
+    return `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 11)}`;
+}
+//# sourceMappingURL=id.js.map

package/dist/utils/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACvD,OAAO,MAAM,CAAC,UAAU,EAAE,CAAC;IAC7B,CAAC;IACD,sDAAsD;IACtD,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;AACrF,CAAC"}

package/{src/utils/index.ts → dist/utils/index.d.ts}

@@ -1,3 +1,5 @@
 export { generateId } from './id.js';
 export { Observable } from './observable.js';
+export { mergeWorkflowErrors } from './workflow-error-utils.js';
 export type { Subscription, Observer } from './observable.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC"}