groundswell 0.0.2 → 1.0.0

package/dist/reflection/reflection.js

@@ -0,0 +1,344 @@
+/**
+ * ReflectionManager - Implements reflection and self-correction for agents
+ *
+ * Provides multi-level reflection (workflow, agent, prompt) with configurable
+ * retry limits and history tracking.
+ */
+import { z } from 'zod';
+/**
+ * Schema for parsing reflection responses from the agent
+ */
+const ReflectionResponseSchema = z.object({
+    shouldRetry: z.boolean(),
+    reason: z.string(),
+    revisedPromptData: z.record(z.unknown()).optional(),
+    revisedSystemPrompt: z.string().optional(),
+});
+/**
+ * Default reflection prompt template
+ */
+const REFLECTION_PROMPT_TEMPLATE = `A previous operation failed with the following error:
+
+Error: {{errorMessage}}
+Stack: {{errorStack}}
+
+Level: {{level}}
+Node: {{nodeName}} ({{nodeId}})
+Attempt: {{attemptNumber}} of {{maxAttempts}}
+
+Previous attempts:
+{{previousAttempts}}
+
+Analyze the error and determine:
+1. Can this operation be retried with modifications?
+2. What changes would help it succeed?
+3. Is this a transient error (worth retrying) or a fundamental issue (should abort)?
+
+Consider:
+- Rate limits and quota errors should NOT be retried via reflection
+- Authentication errors should NOT be retried via reflection
+- Schema validation errors may be retried with revised data
+- Logic errors may be retried with revised prompts
+
+Respond with JSON:
+{
+  "shouldRetry": boolean,
+  "reason": string,
+  "revisedPromptData": { /* optional revised data */ },
+  "revisedSystemPrompt": "optional revised system prompt"
+}`;
+/**
+ * ReflectionManager - Manages reflection and self-correction
+ */
+export class ReflectionManager {
+    config;
+    history = [];
+    agent;
+    eventEmitter;
+    /**
+     * Create a new ReflectionManager
+     * @param config Reflection configuration
+     * @param agent Optional agent to use for reflection analysis
+     */
+    constructor(config, agent) {
+        this.config = config;
+        this.agent = agent;
+    }
+    /**
+     * Set the event emitter for workflow events
+     */
+    setEventEmitter(emitter) {
+        this.eventEmitter = emitter;
+    }
+    /**
+     * Check if reflection is enabled
+     */
+    isEnabled() {
+        return this.config.enabled;
+    }
+    /**
+     * Get the maximum number of attempts
+     */
+    getMaxAttempts() {
+        return this.config.maxAttempts;
+    }
+    /**
+     * Get the retry delay in milliseconds
+     */
+    getRetryDelayMs() {
+        return this.config.retryDelayMs ?? 0;
+    }
+    /**
+     * Trigger a reflection on the current context
+     */
+    async triggerReflection(reason) {
+        if (!this.config.enabled) {
+            throw new Error('Reflection is not enabled');
+        }
+        // Record that reflection was triggered
+        const entry = {
+            timestamp: Date.now(),
+            level: 'workflow',
+            reason: reason ?? 'Manual reflection trigger',
+            error: new Error(reason ?? 'Manual trigger'),
+            resolution: 'skip',
+            success: false,
+        };
+        this.history.push(entry);
+    }
+    /**
+     * Get the history of reflection attempts
+     */
+    getReflectionHistory() {
+        return [...this.history];
+    }
+    /**
+     * Perform reflection analysis on an error
+     */
+    async reflect(context) {
+        // Emit reflection start event
+        if (this.eventEmitter) {
+            this.eventEmitter({
+                type: 'reflectionStart',
+                level: context.level,
+                node: context.failedNode,
+            });
+        }
+        let result;
+        try {
+            // Check for non-retryable errors
+            if (this.isNonRetryableError(context.error)) {
+                result = {
+                    shouldRetry: false,
+                    reason: `Non-retryable error: ${context.error.message}`,
+                };
+            }
+            else if (this.agent) {
+                // Use agent for reflection analysis
+                result = await this.reflectWithAgent(context);
+            }
+            else {
+                // Use simple heuristic-based reflection
+                result = this.reflectWithHeuristics(context);
+            }
+            // Record the reflection entry
+            const entry = {
+                timestamp: Date.now(),
+                level: context.level,
+                reason: result.reason,
+                error: context.error,
+                resolution: result.shouldRetry ? 'retry' : 'abort',
+                success: false, // Will be updated by caller if retry succeeds
+            };
+            this.history.push(entry);
+            // Apply retry delay if configured
+            if (result.shouldRetry && this.config.retryDelayMs) {
+                await this.delay(this.config.retryDelayMs);
+            }
+            return result;
+        }
+        finally {
+            // Emit reflection end event
+            if (this.eventEmitter) {
+                this.eventEmitter({
+                    type: 'reflectionEnd',
+                    level: context.level,
+                    success: result?.shouldRetry ?? false,
+                    node: context.failedNode,
+                });
+            }
+        }
+    }
+    /**
+     * Mark the last reflection entry as successful
+     */
+    markLastReflectionSuccessful() {
+        if (this.history.length > 0) {
+            this.history[this.history.length - 1].success = true;
+        }
+    }
+    /**
+     * Check if an error is non-retryable
+     */
+    isNonRetryableError(error) {
+        const message = error.message.toLowerCase();
+        // Rate limit and quota errors
+        if (message.includes('rate limit') ||
+            message.includes('quota exceeded') ||
+            message.includes('429')) {
+            return true;
+        }
+        // Authentication errors
+        if (message.includes('authentication') ||
+            message.includes('unauthorized') ||
+            message.includes('401') ||
+            message.includes('403') ||
+            message.includes('invalid api key')) {
+            return true;
+        }
+        // Network errors that should use exponential backoff instead
+        if (message.includes('econnrefused') ||
+            message.includes('etimedout') ||
+            message.includes('network')) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Perform reflection using an agent
+     */
+    async reflectWithAgent(context) {
+        if (!this.agent) {
+            throw new Error('No agent configured for reflection');
+        }
+        // Build the reflection prompt
+        const promptText = this.buildReflectionPrompt(context);
+        // Create a prompt for reflection analysis
+        const reflectionPrompt = new (await import('../core/prompt.js')).Prompt({
+            user: promptText,
+            responseFormat: ReflectionResponseSchema,
+        });
+        try {
+            const response = await this.agent.prompt(reflectionPrompt);
+            // Handle AgentResponse return type
+            if (response.status === 'error') {
+                return {
+                    shouldRetry: false,
+                    reason: `Reflection analysis failed: ${response.error?.message ?? 'Unknown error'}`,
+                };
+            }
+            // Type assertion: data is non-null when status is not 'error'
+            const data = response.data;
+            if (!data) {
+                return {
+                    shouldRetry: false,
+                    reason: 'Reflection analysis failed: No data returned',
+                };
+            }
+            return {
+                shouldRetry: data.shouldRetry,
+                reason: data.reason,
+                revisedPromptData: data.revisedPromptData,
+                revisedSystemPrompt: data.revisedSystemPrompt,
+            };
+        }
+        catch (reflectionError) {
+            // If reflection itself fails, don't retry the original
+            return {
+                shouldRetry: false,
+                reason: `Reflection analysis failed: ${reflectionError instanceof Error ? reflectionError.message : 'Unknown error'}`,
+            };
+        }
+    }
+    /**
+     * Perform reflection using simple heuristics
+     */
+    reflectWithHeuristics(context) {
+        const errorMessage = context.error.message.toLowerCase();
+        // Check for validation errors (often retryable)
+        if (errorMessage.includes('validation') ||
+            errorMessage.includes('parse') ||
+            errorMessage.includes('schema') ||
+            errorMessage.includes('json')) {
+            return {
+                shouldRetry: true,
+                reason: 'Validation/parsing error detected - retry may succeed with adjusted approach',
+            };
+        }
+        // Check for timeout errors
+        if (errorMessage.includes('timeout')) {
+            return {
+                shouldRetry: context.attemptNumber < 2,
+                reason: context.attemptNumber < 2
+                    ? 'Timeout error - retry once'
+                    : 'Timeout error - too many attempts',
+            };
+        }
+        // Default: retry if under max attempts
+        const shouldRetry = context.attemptNumber < this.config.maxAttempts;
+        return {
+            shouldRetry,
+            reason: shouldRetry
+                ? `Attempt ${context.attemptNumber} failed - retrying`
+                : `Max attempts (${this.config.maxAttempts}) reached`,
+        };
+    }
+    /**
+     * Build the reflection prompt from context
+     */
+    buildReflectionPrompt(context) {
+        const previousAttemptsText = context.previousAttempts.length > 0
+            ? context.previousAttempts
+                .map((a, i) => `  ${i + 1}. [${a.level}] ${a.reason} -> ${a.resolution} (${a.success ? 'success' : 'failed'})`)
+                .join('\n')
+            : '  None';
+        return REFLECTION_PROMPT_TEMPLATE.replace('{{errorMessage}}', context.error.message)
+            .replace('{{errorStack}}', context.error.stack ?? 'No stack trace')
+            .replace('{{level}}', context.level)
+            .replace('{{nodeName}}', context.failedNode.name)
+            .replace('{{nodeId}}', context.failedNode.id)
+            .replace('{{attemptNumber}}', String(context.attemptNumber))
+            .replace('{{maxAttempts}}', String(this.config.maxAttempts))
+            .replace('{{previousAttempts}}', previousAttemptsText);
+    }
+    /**
+     * Helper to create a delay
+     */
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+/**
+ * Execute a function with reflection support
+ * @param fn Function to execute
+ * @param reflection ReflectionManager instance
+ * @param createContext Function to create reflection context from error
+ * @returns Result of the function
+ */
+export async function executeWithReflection(fn, reflection, createContext) {
+    let lastError = null;
+    const maxAttempts = reflection.getMaxAttempts();
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const result = await fn();
+            // If we succeeded after a reflection, mark it as successful
+            if (attempt > 1) {
+                reflection.markLastReflectionSuccessful();
+            }
+            return result;
+        }
+        catch (error) {
+            lastError = error;
+            if (!reflection.isEnabled() || attempt === maxAttempts) {
+                throw error;
+            }
+            const context = createContext(lastError, attempt, reflection.getReflectionHistory());
+            const result = await reflection.reflect(context);
+            if (!result.shouldRetry) {
+                throw lastError;
+            }
+        }
+    }
+    throw lastError ?? new Error('Max reflection attempts exceeded');
+}
+//# sourceMappingURL=reflection.js.map

package/dist/reflection/reflection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflection.js","sourceRoot":"","sources":["../../src/reflection/reflection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE;IACxB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,iBAAiB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACnD,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC3C,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,0BAA0B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BjC,CAAC;AAEH;;GAEG;AACH,MAAM,OAAO,iBAAiB;IACX,MAAM,CAAmB;IACzB,OAAO,GAAsB,EAAE,CAAC;IAChC,KAAK,CAAS;IACvB,YAAY,CAAkC;IAEtD;;;;OAIG;IACH,YAAY,MAAwB,EAAE,KAAa;QACjD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,OAAuC;QACrD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,iBAAiB,CAAC,MAAe;QACrC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC/C,CAAC;QAED,uCAAuC;QACvC,MAAM,KAAK,GAAoB;YAC7B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,KAAK,EAAE,UAAU;YACjB,MAAM,EAAE,MAAM,IAAI,2BAA2B;YAC7C,KAAK,EAAE,IAAI,KAAK,CAAC,MAAM,IAAI,gBAAgB,CAAC;YAC5C,UAAU,EAAE,MAAM;YAClB,OAAO,EAAE,KAAK;SACf,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,oBAAoB;QAClB,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,OAA0B;QACtC,8BAA8B;QAC9B,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,IAAI,CAAC,YAAY,CAAC;gBAChB,IAAI,EAAE,iBAAiB;gBACvB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,IAAI,EAAE,OAAO,CAAC,UAAU;aACzB,CAAC,CAAC;QACL,CAAC;QAED,IAAI,MAAwB,CAAC;QAE7B,IAAI,CAAC;YACH,iCAAiC;YACjC,IAAI,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBAC5C,MAAM,GAAG;oBACP,WAAW,EAAE,KAAK;oBAClB,MAAM,EAAE,wBAAwB,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE;iBACxD,CAAC;YACJ,CAAC;iBAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACtB,oCAAoC;gBACpC,MAAM,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;YAChD,CAAC;iBAAM,CAAC;gBACN,wCAAwC;gBACxC,MAAM,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;YAC/C,CAAC;YAED,8BAA8B;YAC9B,MAAM,KAAK,GAAoB;gBAC7B,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;gBACrB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,UAAU,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO;gBAClD,OAAO,EAAE,KAAK,EAAE,8CAA8C;aAC/D,CAAC;YAEF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAEzB,kCAAkC;YAClC,IAAI,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC;gBACnD,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YAC7C,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;gBAAS,CAAC;YACT,4BAA4B;YAC5B,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACtB,IAAI,CAAC,YAAY,CAAC;oBAChB,IAAI,EAAE,eAAe;oBACrB,KAAK,EAAE,OAAO,CAAC,KAAK;oBACpB,OAAO,EAAE,MAAO,EAAE,WAAW,IAAI,KAAK;oBACtC,IAAI,EAAE,OAAO,CAAC,UAAU;iBACzB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,4BAA4B;QAC1B,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,GAAG,IAAI,CAAC;QACvD,CAAC;IACH,CAAC;IAED;;OAEG;IACK,mBAAmB,CAAC,KAAY;QACtC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QAE5C,8BAA8B;QAC9B,IACE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;YAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EACvB,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,wBAAwB;QACxB,IACE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;YAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;YACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;YACvB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EACnC,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,6DAA6D;QAC7D,IACE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC;YAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;YAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAC3B,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,gBAAgB,CAC5B,OAA0B;QAE1B,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QAED,8BAA8B;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAEvD,0CAA0C;QAC1C,MAAM,gBAAgB,GAAG,IAAI,CAAC,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC,CAAC,MAAM,CAAC;YACtE,IAAI,EAAE,UAAU;YAChB,cAAc,EAAE,wBAAwB;SACzC,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAC3D,mCAAmC;YACnC,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO,EAAE,CAAC;gBAChC,OAAO;oBACL,WAAW,EAAE,KAAK;oBAClB,MAAM,EAAE,+BAA+B,QAAQ,CAAC,KAAK,EAAE,OAAO,IAAI,eAAe,EAAE;iBACpF,CAAC;YACJ,CAAC;YACD,8DAA8D;YAC9D,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;YAC3B,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,OAAO;oBACL,WAAW,EAAE,KAAK;oBAClB,MAAM,EAAE,8CAA8C;iBACvD,CAAC;YACJ,CAAC;YACD,OAAO;gBACL,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;gBACzC,mBAAmB,EAAE,IAAI,CAAC,mBAAmB;aAC9C,CAAC;QACJ,CAAC;QAAC,OAAO,eAAe,EAAE,CAAC;YACzB,uDAAuD;YACvD,OAAO;gBACL,WAAW,EAAE,KAAK;gBAClB,MAAM,EAAE,+BAA+B,eAAe,YAAY,KAAK,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE;aACtH,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACK,qBAAqB,CAAC,OAA0B;QACtD,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;QAEzD,gDAAgD;QAChD,IACE,YAAY,CAAC,QAAQ,CAAC,YAAY,CAAC;YACnC,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC;YAC9B,YAAY,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAC/B,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,EAC7B,CAAC;YACD,OAAO;gBACL,WAAW,EAAE,IAAI;gBACjB,MAAM,EACJ,8EAA8E;aACjF,CAAC;QACJ,CAAC;QAED,2BAA2B;QAC3B,IAAI,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACrC,OAAO;gBACL,WAAW,EAAE,OAAO,CAAC,aAAa,GAAG,CAAC;gBACtC,MAAM,EACJ,OAAO,CAAC,aAAa,GAAG,CAAC;oBACvB,CAAC,CAAC,4BAA4B;oBAC9B,CAAC,CAAC,mCAAmC;aAC1C,CAAC;QACJ,CAAC;QAED,uCAAuC;QACvC,MAAM,WAAW,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC;QACpE,OAAO;YACL,WAAW;YACX,MAAM,EAAE,WAAW;gBACjB,CAAC,CAAC,WAAW,OAAO,CAAC,aAAa,oBAAoB;gBACtD,CAAC,CAAC,iBAAiB,IAAI,CAAC,MAAM,CAAC,WAAW,WAAW;SACxD,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,qBAAqB,CAAC,OAA0B;QACtD,MAAM,oBAAoB,GACxB,OAAO,CAAC,gBAAgB,CAAC,MAAM,GAAG,CAAC;YACjC,CAAC,CAAC,OAAO,CAAC,gBAAgB;iBACrB,GAAG,CACF,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,GAAG,CAClG;iBACA,IAAI,CAAC,IAAI,CAAC;YACf,CAAC,CAAC,QAAQ,CAAC;QAEf,OAAO,0BAA0B,CAAC,OAAO,CAAC,kBAAkB,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC;aACjF,OAAO,CAAC,gBAAgB,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,gBAAgB,CAAC;aAClE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC;aACnC,OAAO,CAAC,cAAc,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;aAChD,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;aAC5C,OAAO,CAAC,mBAAmB,EAAE,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;aAC3D,OAAO,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;aAC3D,OAAO,CAAC,sBAAsB,EAAE,oBAAoB,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,EAAoB,EACpB,UAA6B,EAC7B,aAIsB;IAEtB,IAAI,SAAS,GAAiB,IAAI,CAAC;IACnC,MAAM,WAAW,GAAG,UAAU,CAAC,cAAc,EAAE,CAAC;IAEhD,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACxD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;YAE1B,4DAA4D;YAC5D,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBAChB,UAAU,CAAC,4BAA4B,EAAE,CAAC;YAC5C,CAAC;YAED,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,SAAS,GAAG,KAAc,CAAC;YAE3B,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,IAAI,OAAO,KAAK,WAAW,EAAE,CAAC;gBACvD,MAAM,KAAK,CAAC;YACd,CAAC;YAED,MAAM,OAAO,GAAG,aAAa,CAC3B,SAAS,EACT,OAAO,EACP,UAAU,CAAC,oBAAoB,EAAE,CAClC,CAAC;YAEF,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAEjD,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;gBACxB,MAAM,SAAS,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,SAAS,IAAI,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;AACnE,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tools module exports
+ */
+export { INTROSPECTION_TOOLS, inspectCurrentNodeTool, readAncestorChainTool, listSiblingsChildrenTool, inspectPriorOutputsTool, inspectCacheStatusTool, requestSpawnWorkflowTool, INTROSPECTION_HANDLERS, handleInspectCurrentNode, handleReadAncestorChain, handleListSiblingsChildren, handleInspectPriorOutputs, handleInspectCacheStatus, handleRequestSpawnWorkflow, registerIntrospectionTools, executeIntrospectionTool, } from './introspection.js';
+export type { CurrentNodeInfo, AncestorInfo, AncestorChainResult, NodeInfo, SiblingsChildrenResult, PriorOutputInfo, CacheStatusResult, SpawnWorkflowRequest, } from './introspection.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAEL,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EAExB,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAE1B,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EACV,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,QAAQ,EACR,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,11 @@
+/**
+ * Tools module exports
+ */
+export { 
+// Tool definitions
+INTROSPECTION_TOOLS, inspectCurrentNodeTool, readAncestorChainTool, listSiblingsChildrenTool, inspectPriorOutputsTool, inspectCacheStatusTool, requestSpawnWorkflowTool, 
+// Handlers
+INTROSPECTION_HANDLERS, handleInspectCurrentNode, handleReadAncestorChain, handleListSiblingsChildren, handleInspectPriorOutputs, handleInspectCacheStatus, handleRequestSpawnWorkflow, 
+// Utilities
+registerIntrospectionTools, executeIntrospectionTool, } from './introspection.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO;AACL,mBAAmB;AACnB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB;AACxB,WAAW;AACX,sBAAsB,EACtB,wBAAwB,EACxB,uBAAuB,EACvB,0BAA0B,EAC1B,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B;AAC1B,YAAY;AACZ,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,oBAAoB,CAAC"}

package/dist/tools/introspection.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Introspection Tools - Standard tools for agents to inspect their workflow hierarchy
+ *
+ * These tools allow agents to understand their position in the workflow tree,
+ * access prior outputs, check cache status, and request dynamic workflow spawning.
+ */
+import type { Tool, WorkflowStatus } from '../types/index.js';
+/**
+ * Information about the current workflow node
+ */
+export interface CurrentNodeInfo {
+    id: string;
+    name: string;
+    status: WorkflowStatus;
+    parentId?: string;
+    parentName?: string;
+    childCount: number;
+    depth: number;
+}
+/**
+ * Information about an ancestor node
+ */
+export interface AncestorInfo {
+    id: string;
+    name: string;
+    status: WorkflowStatus;
+    depth: number;
+}
+/**
+ * Result from reading ancestor chain
+ */
+export interface AncestorChainResult {
+    ancestors: AncestorInfo[];
+    totalDepth: number;
+}
+/**
+ * Information about a sibling or child node
+ */
+export interface NodeInfo {
+    id: string;
+    name: string;
+    status: WorkflowStatus;
+}
+/**
+ * Result from listing siblings or children
+ */
+export interface SiblingsChildrenResult {
+    nodes: NodeInfo[];
+    type: 'siblings' | 'children';
+}
+/**
+ * Information about a prior output
+ */
+export interface PriorOutputInfo {
+    nodeId: string;
+    nodeName: string;
+    status: WorkflowStatus;
+    events: unknown[];
+}
+/**
+ * Result from cache status check
+ */
+export interface CacheStatusResult {
+    exists: boolean;
+    key: string;
+}
+/**
+ * Request to spawn a workflow
+ */
+export interface SpawnWorkflowRequest {
+    name: string;
+    description: string;
+    requestId: string;
+    status: 'pending';
+}
+/**
+ * Tool: inspect_current_node
+ * Returns information about the current workflow node
+ */
+export declare const inspectCurrentNodeTool: Tool;
+/**
+ * Tool: read_ancestor_chain
+ * Returns all ancestor nodes from current position up to root
+ */
+export declare const readAncestorChainTool: Tool;
+/**
+ * Tool: list_siblings_children
+ * Returns sibling or child nodes relative to current position
+ */
+export declare const listSiblingsChildrenTool: Tool;
+/**
+ * Tool: inspect_prior_outputs
+ * Returns outputs from prior steps or prompt executions
+ */
+export declare const inspectPriorOutputsTool: Tool;
+/**
+ * Tool: inspect_cache_status
+ * Checks if a prompt response is cached
+ */
+export declare const inspectCacheStatusTool: Tool;
+/**
+ * Tool: request_spawn_workflow
+ * Requests to spawn a new child workflow dynamically
+ */
+export declare const requestSpawnWorkflowTool: Tool;
+/**
+ * Handler for inspect_current_node
+ */
+export declare function handleInspectCurrentNode(): Promise<CurrentNodeInfo>;
+/**
+ * Handler for read_ancestor_chain
+ */
+export declare function handleReadAncestorChain(input: {
+    maxDepth?: number;
+}): Promise<AncestorChainResult>;
+/**
+ * Handler for list_siblings_children
+ */
+export declare function handleListSiblingsChildren(input: {
+    type: 'siblings' | 'children';
+}): Promise<SiblingsChildrenResult>;
+/**
+ * Handler for inspect_prior_outputs
+ */
+export declare function handleInspectPriorOutputs(input: {
+    nodeId?: string;
+    count?: number;
+}): Promise<PriorOutputInfo[]>;
+/**
+ * Handler for inspect_cache_status
+ */
+export declare function handleInspectCacheStatus(input: {
+    promptHash: string;
+}): Promise<CacheStatusResult>;
+/**
+ * Handler for request_spawn_workflow
+ * Note: This creates a spawn request that must be handled by the workflow orchestrator
+ */
+export declare function handleRequestSpawnWorkflow(input: {
+    name: string;
+    description: string;
+}): Promise<SpawnWorkflowRequest>;
+/**
+ * All introspection tools bundled together
+ */
+export declare const INTROSPECTION_TOOLS: Tool[];
+/**
+ * Map of tool names to handlers
+ */
+export declare const INTROSPECTION_HANDLERS: Record<string, (input: unknown) => Promise<unknown>>;
+/**
+ * Register all introspection tools with an MCP handler
+ * @param handler MCP handler to register tools with
+ */
+export declare function registerIntrospectionTools(handler: {
+    registerTool(name: string, executor: (input: unknown) => Promise<unknown>): void;
+}): void;
+/**
+ * Execute an introspection tool by name
+ * @param toolName Name of the tool to execute
+ * @param input Tool input
+ * @returns Tool result
+ */
+export declare function executeIntrospectionTool(toolName: string, input: unknown): Promise<unknown>;
+//# sourceMappingURL=introspection.d.ts.map

package/dist/tools/introspection.d.ts.map

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